CentOS docs - Apr 2016 - discussions around upstream documentation

On Mon, Apr 11, 2016 at 10:37 AM, Karsten Wade <kwade at redhat.com>
wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 04/11/2016 09:18 AM, Jim Perrin wrote:
>> What are the thoughts or concerns about this sort of workflow
>> change?
>
> Any chance Moin Moin can store wiki source in git and sync
> automatically with a central git repository?
>
> It would provide another pathway to suggest edits to the wiki without
> requiring wiki edit permissions.
>
> For new documentation, e.g. layered project content from SIGs or
> upstream documentation sources, I would think we'd want to skip a
> conversion to/from Moin Moin and instead work directly in the sources
> from upstream. Eases merging upstream, etc. Last Summer's GSoC
> students implemented such a workflow.
I agree with providing another pathway. More specifically, I am
against moving entirely away from the current way of editing the wiki.

Going for the git environment has its own merits as already mentioned,
but at the same time it would deter some people. Not everyone is
particularly fond of (or familiar with) git. I would not be surprised
if some of the existing wiki authors stop contributing if the direct
edit is no longer an option.

Akemi

On 11/04/16 21:11, Akemi Yagi wrote:
> On Mon, Apr 11, 2016 at 10:37 AM, Karsten Wade <kwade at redhat.com>
wrote:
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>>
>> On 04/11/2016 09:18 AM, Jim Perrin wrote:
>>> What are the thoughts or concerns about this sort of workflow
>>> change?
>>
>> Any chance Moin Moin can store wiki source in git and sync
>> automatically with a central git repository?
>>
>> It would provide another pathway to suggest edits to the wiki without
>> requiring wiki edit permissions.
>>
>> For new documentation, e.g. layered project content from SIGs or
>> upstream documentation sources, I would think we'd want to skip a
>> conversion to/from Moin Moin and instead work directly in the sources
>> from upstream. Eases merging upstream, etc. Last Summer's GSoC
>> students implemented such a workflow.
> 
> I agree with providing another pathway. More specifically, I am
> against moving entirely away from the current way of editing the wiki.
> 
> Going for the git environment has its own merits as already mentioned,
> but at the same time it would deter some people. Not everyone is
> particularly fond of (or familiar with) git. I would not be surprised
> if some of the existing wiki authors stop contributing if the direct
> edit is no longer an option.
> 
> Akemi
That's what I fear too. A wiki is something that has to be edited live,
and be quick/fast.
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 at http://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$


-- 
Fabian Arrotin
The CentOS Project | http://www.centos.org
gpg key: 56BEC54E | twitter: @arrfab

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: OpenPGP digital signature
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20160412/68b57e0a/attachment.sig>

On 04/12/2016 08:11 AM, Fabian Arrotin wrote:
> On 11/04/16 21:11, Akemi Yagi wrote:
>> >On Mon, Apr 11, 2016 at 10:37 AM, Karsten Wade<kwade at
redhat.com>  wrote:
>>> >>-----BEGIN PGP SIGNED MESSAGE-----
>>> >>Hash: SHA1
>>> >>
>>> >>On 04/11/2016 09:18 AM, Jim Perrin wrote:
>>>> >>>What are the thoughts or concerns about this sort
of workflow
>>>> >>>change?
>>> >>
>>> >>Any chance Moin Moin can store wiki source in git and sync
>>> >>automatically with a central git repository?
>>> >>
>>> >>It would provide another pathway to suggest edits to the
wiki without
>>> >>requiring wiki edit permissions.
>>> >>
>>> >>For new documentation, e.g. layered project content from
SIGs or
>>> >>upstream documentation sources, I would think we'd want
to skip a
>>> >>conversion to/from Moin Moin and instead work directly in
the sources
>>> >>from upstream. Eases merging upstream, etc. Last
Summer's GSoC
>>> >>students implemented such a workflow.
>> >
>> >I agree with providing another pathway. More specifically, I am
>> >against moving entirely away from the current way of editing the
wiki.
>> >
>> >Going for the git environment has its own merits as already
mentioned,
>> >but at the same time it would deter some people. Not everyone is
>> >particularly fond of (or familiar with) git. I would not be
surprised
>> >if some of the existing wiki authors stop contributing if the
direct
>> >edit is no longer an option.
>> >
>> >Akemi
> That's what I fear too. A wiki is something that has to be edited live,
> and be quick/fast.
+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.


> 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.