[CentOS-docs] discussions around upstream documentation

Tue Apr 12 05:11:37 UTC 2016
Fabian Arrotin <arrfab at centos.org>

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