[CentOS-docs] discussions around upstream documentation

Tue Apr 12 18:05:48 UTC 2016
Jim Perrin <jperrin at centos.org>

On 04/12/2016 01:17 AM, Manuel Wolfshant wrote:

> +1 here. A wiki has an "edit button" , a "preview button" and a "save
> button". It's not a "commit to git, pull from git, format for wiki,
> whatever" dance. It's already hard enough that people need to create a
> wiki account, subscribe to a mailing list ( with a different account BTW
> ), announce their intention and request real access, wait for access.

Actually that's sort of the same workflow for git docs within some
systems. You can have an 'edit' button, and make changes. If you have
write access, your changes get merged immediately. If not, your changes
get created as a pull request where someone has to review it and pull it

>> Git-based doc is probably something more formalized and for tech writers
>> having to maintain an "official" doc.
>> I (in the past) had a look athttp://www.mkdocs.org/  for this (and so
>> all the .md can be in a public git repo that people can submit PR to)
>> While personally I don't mind switching to something using git in the
>> workflow, I'm wondering if such tool shouldn't be used instead to target
>> "official" docs under centos.org/docs and not the wiki. (both can be
>> complementary)
>> just my 0.02$
> Another +1 here as well. Let's focus on $SUBJECT.
> The issue at hand is not the wiki ( and its workflow ) but the content
> from https://www.centos.org/docs/ which is
> a) deprecated for years
> b) unmaintainable by the community.
> There is no public info on who has access to update the above link or
> even what should ( and what should NOT ) get published there. It's
> assumed that the content should replicate ( adjusted as needed i.e.
> respecting trademarks , branding and so on plus removing/replacing
> references to the parts of RHEL not relevant for CentOS ) the content
> from upstream. However since CentOS 6 was launched, short of rumors
> around "we cannot do that because of legal stuff" nothing was ever done.
> All we have now is documentation for long long long dead releases ( 2,
> 3, 4 ) and some copies of the RHEL 5 docs, 3 or more years old. We do
> not even have a pointer along "take with a grain a salt the information
> from the upstream docs hosted at access.redhat.com" which still would be
> more than nothing and would alleviate a bit ( or at least complement )
> the need for the @docs trigger in #centos.
> Before discussing tooling , IMNSHO we should focus on the actual content
> that we want/need to publish and the method to create and deliver it.
> Using publican, mkdocs or whatever method to generate web pages from
> "something" should be the result of this discussion, not the preamble.

This is mostly correct, and I worded the initial bit improperly. The FAD
meeting is specifically about 'official' documentation, which needs a
more formal structure, and a massive update.

That very likely will be git based because that's how upstream is
working, both on the RHEL side and Fedora. We can *add* to or correct
the documentation we get within that workflow. My thinking was that we
could bring some (or all) of the wiki content into that new structure,
rather than pointing people to multiple locations for docs, but that
doesn't have to happen. They can absolutely each be
standalone/complimentary resources.

Jim Perrin
The CentOS Project | http://www.centos.org
twitter: @BitIntegrity | GPG Key: FA09AD77