On 25/08/2022 16:10, Trevor Hemsley via CentOS-devel wrote:
> On 25/08/2022 15:28, Robby Callicotte via CentOS-devel wrote:
>> On Thursday, August 25, 2022 8:46:18 AM CDT Neal Gompa wrote:
>>> I second this. Our quick docs could use MkDocs like the SIG stuff
>>> does, and the RHELish stuff can use the Antora system the RHEL docs
>>> folks want to use.
>> I agree with Neal here. This seems to offer a good balance. At this
>> point I
>> would argue that the MR/PR nature of git is ubiquitous and is part of
>> everyone's workflow.
>
> So far I've seen lots of "yes, use this" type comments so I'd like to
> ask how this compares in user friendliness to the current wiki (assuming
> that you can get to it because the spammers are taking a rest). I've
> never used any of the alternatives that have been proposed so far. Are
> they wikis? Are they usable for a non-technical user? The wiki, you
> press a button and you can edit content directly and see what it will
> look like before you save it. You can link to other pages easily, you
> can format content how you want it easily, often just at the press of a
> button.
>
> None of what I've heard so far sounds even remotely as usable as what we
> have now.
>
> Trevor
I agree.
Git-type work flows, pull and merge requests may be second nature to
those working within Red Hat, or other developers, but they are not
familiar technologies to most non-technical, regular users.
The Wiki has served as a key point of entry for contributing to the
CentOS project for non-technical users for exactly the reasons Trevor
highlights. A user can easily read and follow the documentation
presented on the Wiki, and can easily update it to fix any errors they
may encounter at the press of a button. If we lose that ability then we
lose a valuable entry point for new contributors to the project.
And lets not forget - developers do not write (or maintain) web-based
documentation. That is the reason documentation sucks on most open
source projects - developers want to do cool stuff, not spend all their
time writing documentation. So lets not give too much weight to the
opinions of those who have never contributed anything to the Wiki.
Fabian - please can you give us stats for the top contributors so we can
seek and appropriately weigh their opinions?
My main worry is that we are asking for their opinion of a sinking ship after the third torpedo has hit it. The current wiki runs due to a lot of hard work by Fabian and some others to keep it working. It is DOS'd daily, it is corrupted monthly, and it goes into strange lockdown modes regularly. You try to edit some pages in one editor and you can corrupt an entire section. Various people have hacked as many fixes as they can and Fabian has put in a LOT of off-hours work via 'ping' to fix other things for the last decade. Having worked with Fabian for a decade, him saying the wiki is dieing on an open list is a "The ship is sinking fast, I am going to keep trying to fix it until it goes, but you all might want to get on those lifeboats now." I realize that this isn't a new issue, people have been complaining about how fragile the CentOS wiki has been before Red Hat acquired the main team. However we have run out of street to kick the can down anymore.
I don't know about the other people's reasons for bringing up the git/markdown workflow but I did from my experience trying to keep the Fedora wiki from sinking these last 10 years also. The documentation community in Fedora and other areas are moving to git workflows with static pages. Many are just using github editor and
readthedocs.io tools, and various CI/CD chains in github as their wiki replacements.
The main reason for this is that it breaks down the major way that spambots and dosbots kill wikis due to their using the same php/perl/python/etc to edit, render, and store pages. You overload one of those 3 and you kill the other two. Mediawiki and commercial wikis have a large amount of staff and hardware to try and make that less fragile. For sites without that, it has been easier to go to a slower method where edits are done in say github, sent through some sort of CI and then a pr made to merge by the master web doc person. That is then pushed to the various web servers for viewing. It is a lot slower but also less prone to SPAM/DOS problems.
In the end, one of the following is going to happen:
1. The CentOS wiki dies to the point where the only solution is a static rendering from backups of the last good wiki.
2. A team of people take over the moinmoin python code and start fixing CentOS issues. This is then wrapped with a new layer approach to deal with SPAM/DOS issues.
3. A team of people come up with a new architecture for a replacement wiki (be it twiki, mediawiki, etc) which is more resilient and upstream maintained for cve's etc.
4. A different method of documentation writing and editing is come up with and implemented.
5. Some other idea?