There is a Fedora Activity Day (https://fedoraproject.org/wiki/FAD_Documentation_2016 ) centered around documentation, where I'm going to see what can be done about the state of centos documentation from upstream sources. Most of the tooling for documentation for these two groups is centered around git. For the most part, our documentation currently lives in the wiki, and has a fairly high barrier to new contributors. Would the regulars who contribute on the wiki consider consider supporting a migration to a git based documentation workflow? I think this would help lower the barrier to contribution by allowing new contributors to submit a pull request or patch for documentation rather than join a mailing list, request access, etc. What are the thoughts or concerns about this sort of workflow change? -- Jim Perrin The CentOS Project | http://www.centos.org twitter: @BitIntegrity | GPG Key: FA09AD77
Karsten Wade
2016-Apr-11 17:37 UTC
[CentOS-docs] discussions around upstream documentation
-----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. Best, - - Karsten - -- Karsten Wade Community Infra & Platform (Mgr) Open Source and Standards, @redhatopen @quaid gpg: AD0E0C41 -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iEYEARECAAYFAlcL4N8ACgkQ2ZIOBq0ODEHz/wCgm3Co0QAkcDhb6t1PDL51sZND nggAniBSEE3KBnZvE2Zbr/h7Zb8y1Nt1 =Oy/2 -----END PGP SIGNATURE-----
Christoph Galuschka
2016-Apr-11 18:30 UTC
[CentOS-docs] discussions around upstream documentation
Hi Jim, Am 11.04.2016 um 18:18 schrieb Jim Perrin:> There is a Fedora Activity Day > (https://fedoraproject.org/wiki/FAD_Documentation_2016 ) centered around > documentation, where I'm going to see what can be done about the state > of centos documentation from upstream sources. > > Most of the tooling for documentation for these two groups is centered > around git. For the most part, our documentation currently lives in the > wiki, and has a fairly high barrier to new contributors. > > Would the regulars who contribute on the wiki consider consider > supporting a migration to a git based documentation workflow?I would be fine with such a move.> > I think this would help lower the barrier to contribution by allowing > new contributors to submit a pull request or patch for documentation > rather than join a mailing list, request access, etc.Agreed. Similar to what we do with t_functional tests.> > What are the thoughts or concerns about this sort of workflow change? > > > >all the best Christoph -- Christoph Galuschka CentOS-QA-Team member | IRC: tigalch
François Cami
2016-Apr-11 18:59 UTC
[CentOS-docs] discussions around upstream documentation
On Mon, Apr 11, 2016 at 8:30 PM, Christoph Galuschka <tigalch at tigalch.org> wrote:> Hi Jim, > > Am 11.04.2016 um 18:18 schrieb Jim Perrin: >> >> There is a Fedora Activity Day >> (https://fedoraproject.org/wiki/FAD_Documentation_2016 ) centered around >> documentation, where I'm going to see what can be done about the state >> of centos documentation from upstream sources. >> >> Most of the tooling for documentation for these two groups is centered >> around git. For the most part, our documentation currently lives in the >> wiki, and has a fairly high barrier to new contributors. >> >> Would the regulars who contribute on the wiki consider consider >> supporting a migration to a git based documentation workflow? > > > I would be fine with such a move.Me too.>> I think this would help lower the barrier to contribution by allowing >> new contributors to submit a pull request or patch for documentation >> rather than join a mailing list, request access, etc. > > > Agreed. Similar to what we do with t_functional tests. >> >> >> What are the thoughts or concerns about this sort of workflow change? >> >> >> >> > all the best > Christoph > -- > Christoph Galuschka > CentOS-QA-Team member | IRC: tigalch > > _______________________________________________ > CentOS-docs mailing list > CentOS-docs at centos.org > https://lists.centos.org/mailman/listinfo/centos-docs
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
Brian (bex) Exelbierd
2016-May-17 09:07 UTC
[CentOS-docs] discussions around upstream documentation
Jim, What were the outcomes from a CentOS perspective? thank you. regards, bex On 04/11/2016 06:18 PM, Jim Perrin wrote:> There is a Fedora Activity Day > (https://fedoraproject.org/wiki/FAD_Documentation_2016 ) centered around > documentation, where I'm going to see what can be done about the state > of centos documentation from upstream sources. > > Most of the tooling for documentation for these two groups is centered > around git. For the most part, our documentation currently lives in the > wiki, and has a fairly high barrier to new contributors. > > Would the regulars who contribute on the wiki consider consider > supporting a migration to a git based documentation workflow? > > I think this would help lower the barrier to contribution by allowing > new contributors to submit a pull request or patch for documentation > rather than join a mailing list, request access, etc. > > What are the thoughts or concerns about this sort of workflow change? > > > >-- Brian (bex) Exelbierd | bex at pobox.com +420-606-055-877 | @bexelbie http://www.winglemeyer.org
The Fedora team is working on moving away from docbook and xml to asciidoc. This is a more straightforward approach in the file, with a reasonably easy syntax to learn. This will let us keep docs in git so that users who find something and want to fix it can simply submit a pull request or patch to update and someone responsible can approve or deny it. In the future, it means that non-wiki docs should be easily consumable and editable. That doesn't help us for the current state of documentation, but it does help to resolve things for the future. I'm still working on the state of the existing docs via a few contacts I made at the docs day. On 05/17/2016 04:07 AM, Brian (bex) Exelbierd wrote:> Jim, > > What were the outcomes from a CentOS perspective? > > thank you. > > regards, > > bex > > On 04/11/2016 06:18 PM, Jim Perrin wrote: >> There is a Fedora Activity Day >> (https://fedoraproject.org/wiki/FAD_Documentation_2016 ) centered around >> documentation, where I'm going to see what can be done about the state >> of centos documentation from upstream sources. >> >> Most of the tooling for documentation for these two groups is centered >> around git. For the most part, our documentation currently lives in the >> wiki, and has a fairly high barrier to new contributors. >> >> Would the regulars who contribute on the wiki consider consider >> supporting a migration to a git based documentation workflow? >> >> I think this would help lower the barrier to contribution by allowing >> new contributors to submit a pull request or patch for documentation >> rather than join a mailing list, request access, etc. >> >> What are the thoughts or concerns about this sort of workflow change? >> >> >> >> >-- Jim Perrin The CentOS Project | http://www.centos.org twitter: @BitIntegrity | GPG Key: FA09AD77