Re: [CentOS-docs] discussions around upstream documentation

2016-05-17 Thread Jim Perrin 
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
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-05-17 Thread Brian (bex) Exelbierd 

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 | b...@pobox.com
+420-606-055-877 | @bexelbie
http://www.winglemeyer.org
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-12 Thread Jim Perrin 


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

> 
> 
> 
>> 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
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-12 Thread Manuel Wolfshant 

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


___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-11 Thread Fabian Arrotin 
On 11/04/16 21:11, Akemi Yagi wrote:
> On Mon, Apr 11, 2016 at 10:37 AM, Karsten Wade  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



signature.asc
Description: OpenPGP digital signature
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-11 Thread Akemi Yagi 
On Mon, Apr 11, 2016 at 10:37 AM, Karsten Wade  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
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-11 Thread François Cami 
On Mon, Apr 11, 2016 at 8:30 PM, Christoph Galuschka
 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@centos.org
> https://lists.centos.org/mailman/listinfo/centos-docs
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-11 Thread Christoph Galuschka 

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
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs

Re: [CentOS-docs] discussions around upstream documentation

2016-04-11 Thread Karsten Wade 
-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-
___
CentOS-docs mailing list
CentOS-docs@centos.org
https://lists.centos.org/mailman/listinfo/centos-docs