On 25/08/2022 16:32, Phil Perry wrote:
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.
I think my point above is further highlighted by the fact this
discussion is taking place on the centos-devel list, not the centos-docs
list.
Fabian - please can you give us stats for the top contributors so we can
seek and appropriately weigh their opinions?
Thanks
_______________________________________________
CentOS-docs mailing list
CentOS-docs@xxxxxxxxxx
https://lists.centos.org/mailman/listinfo/centos-docs
