CentOS docs - Aug 2015 - How GSoC project can fit in to CentOS Docs

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

There have been some questions about how the GSoC project interacts
with the existing documentation work that happens around the wiki.

Let's get all the open questions in to this thread and discuss them.

Lei, Kunaal -- What other open questions do we have?

Anyone else with open questions?

The GSoC project is supposed to be additive to what we do -- an
additional way to get new contributions submitted, reviewed, and ready
for publishing.

Where things are published is still an open question for this group
(centos-docs) to decide.

The toolchain basically takes submissions in common markup formats
made via GitHub. It puts them in a queue for an editorial team to
review. When ready, the tool can publish or make content ready for
publishing.

The content could be new articles, or repurposed content from e.g.
blogs (with appropriate open licensing.) There is a lot of content out
there about how to do things with CentOS, but most of the original
authors aren't going to go through the process of requesting a wiki
account and publishing here.

For where to publish from the toolchain, if we want to keep all docs
in the wiki, we should plan to have the tool output to MoinMoin wiki
syntax so that one of the existing editors can copy/paste in to an
existing or new wiki article. This wiki publishing would work for
shorter form content.

So the new tool could be a way for people to submit edits to existing
wiki articles without having to get a wiki account.

Some open questions:

* Who can/wants to be on the editorial board?
* Where do we want to publish longer documents?

For example, if we had the sources for one of the RHEL documents in
Git, it would be straightforward to modify that document for CentOS,
and even add to it, via this new toolchain.

Would we want to put that in to a series of wiki articles? Or publish
it directly to centos.org/docs in HTML and PDF format?

Regards,

- - Karsten
- -- 
Karsten 'quaid' Wade        .^\          CentOS Doer of Stuff
http://TheOpenSourceWay.org    \  http://community.redhat.com
@quaid (identi.ca/twitter/IRC)  \v'             gpg: AD0E0C41

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iEYEARECAAYFAlW6QfUACgkQ2ZIOBq0ODEE2mgCfdVVwHfQvVAJlKMMhHAiMxaM0
UwEAoIGEgCSZKB2DdCIzD/CwLousTW6R
=l4+O
-----END PGP SIGNATURE-----

Would start with the note that the basic project is complete. I would be
releasing the prototype on a separate thread. But for the discussion sake
the workflow will look like this :
Authors contribute content in markdown format, on github.
The pull request created gets mirrored to pagure thus saving dependency on
github.
Also the PR content is built using CI to preview how it looks.
The PR is two way synced between the platforms, so that individual can use
pagure or github.
Once staff approves the post, website is built and deployed.

On Thu, Jul 30, 2015 at 8:55 PM, Karsten Wade <kwade at redhat.com> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> There have been some questions about how the GSoC project interacts
> with the existing documentation work that happens around the wiki.
>
> Let's get all the open questions in to this thread and discuss them.
>
> Lei, Kunaal -- What other open questions do we have?
>
>From my experience till now, CentOS community is little doubtful about the
project. We continued project still, now that we have done the basics,
would be great if CentOS tests it, and gives us suggestions.
>
> Anyone else with open questions?
>
> The GSoC project is supposed to be additive to what we do -- an
> additional way to get new contributions submitted, reviewed, and ready
> for publishing.
>
> Exactly. Proving an alternate and user friendly medium.
> Where things are published is still an open question for this group
> (centos-docs) to decide.
>
Agreed. Maybe a new site containing user curated how to do contents. CentOS
doesnt have to officially endorse the content in this way.
>
> The toolchain basically takes submissions in common markup formats
> made via GitHub. It puts them in a queue for an editorial team to
> review. When ready, the tool can publish or make content ready for
> publishing.
>
In simple words yes :)
>
> The content could be new articles, or repurposed content from e.g.
> blogs (with appropriate open licensing.) There is a lot of content out
> there about how to do things with CentOS, but most of the original
> authors aren't going to go through the process of requesting a wiki
> account and publishing here.
>
> That was the initial motivation you gave to us.
> For where to publish from the toolchain, if we want to keep all docs
> in the wiki, we should plan to have the tool output to MoinMoin wiki
> syntax so that one of the existing editors can copy/paste in to an
> existing or new wiki article. This wiki publishing would work for
> shorter form content.
>
Not sure about this. It adds a human effort in the toolchain.
>
> So the new tool could be a way for people to submit edits to existing
> wiki articles without having to get a wiki account.
> Some open questions:
>
> * Who can/wants to be on the editorial board?
> * Where do we want to publish longer documents?
>
> For example, if we had the sources for one of the RHEL documents in
> Git, it would be straightforward to modify that document for CentOS,
> and even add to it, via this new toolchain.
>
Agreed.
>
> Would we want to put that in to a series of wiki articles? Or publish
> it directly to centos.org/docs in HTML and PDF format?
>
> Regards,
>
> - - Karsten
> - --
> Karsten 'quaid' Wade        .^\          CentOS Doer of Stuff
> http://TheOpenSourceWay.org    \  http://community.redhat.com
> @quaid (identi.ca/twitter/IRC)  \v'             gpg: AD0E0C41
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.22 (GNU/Linux)
>
> iEYEARECAAYFAlW6QfUACgkQ2ZIOBq0ODEE2mgCfdVVwHfQvVAJlKMMhHAiMxaM0
> UwEAoIGEgCSZKB2DdCIzD/CwLousTW6R
> =l4+O
> -----END PGP SIGNATURE-----
> _______________________________________________
> CentOS-docs mailing list
> CentOS-docs at centos.org
> http://lists.centos.org/mailman/listinfo/centos-docs
>
-- 
Regards,
Kunaal Jain
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20150803/219059f9/attachment.html>

> ? 2015?8?4????12:23?kunaal jain <kunaalus at gmail.com> ???
> 
> 
> Would start with the note that the basic project is complete. I would be
releasing the prototype on a separate thread. But for the discussion sake the
workflow will look like this :
> Authors contribute content in markdown format, on github.
> The pull request created gets mirrored to pagure thus saving dependency on
github.
> Also the PR content is built using CI to preview how it looks.
> The PR is two way synced between the platforms, so that individual can use
pagure or github.
> Once staff approves the post, website is built and deployed.
> 
> On Thu, Jul 30, 2015 at 8:55 PM, Karsten Wade <kwade at redhat.com
<mailto:kwade at redhat.com>> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> There have been some questions about how the GSoC project interacts
> with the existing documentation work that happens around the wiki.
> 
> Let's get all the open questions in to this thread and discuss them.
> 
> Lei, Kunaal -- What other open questions do we have?
> 
> From my experience till now, CentOS community is little doubtful about the
project. We continued project still, now that we have done the basics, would be
great if CentOS tests it, and gives us suggestions.
Yes, we are looking for suggestions to improve it.
>  
> Where things are published is still an open question for this group
> (centos-docs) to decide.
> 
> Agreed. Maybe a new site containing user curated how to do contents. CentOS
doesnt have to officially endorse the content in this way.
Agreed.
> 
> For where to publish from the toolchain, if we want to keep all docs
> in the wiki, we should plan to have the tool output to MoinMoin wiki
> syntax so that one of the existing editors can copy/paste in to an
> existing or new wiki article. This wiki publishing would work for
> shorter form content.
> 
> Not sure about this. It adds a human effort in the toolchain. 
I agree with Kunaal. One of our goals is to provide an automated workflow. Maybe
we can remove the ?copy and paste? step and write a little tool to replace it ;)


Best regards,
Lei
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.centos.org/pipermail/centos-docs/attachments/20150804/3a12202d/attachment-0002.html>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 03/08/15 18:23, kunaal jain wrote:
> 
> Would start with the note that the basic project is complete. I
> would be releasing the prototype on a separate thread. But for the
> discussion sake the workflow will look like this : Authors
> contribute content in markdown format, on github. The pull request
> created gets mirrored to pagure thus saving dependency on github. 
> Also the PR content is built using CI to preview how it looks. The
> PR is two way synced between the platforms, so that individual can 
> use pagure or github. Once staff approves the post, website is
> built and deployed.
> 
<snip>

So, trying to understand the goal : can you define what you mean by
"website is built and deployed" ? Do you mean you produce MoinMoin
compatible syntax and sorted by categories/hierarchy, to then be
automatically synced to wiki.centos.org ?
Or do you mean another (and so parallel) website ?

Wrt pagure, I admit I looked at it and found it cool, plus I know
Pierre-Yves (hey !). But wondering if adding
yet-another-git-server-plus-layer is the way to go in our infra, while
all centos git repositories are hosted on a "gitblit powered" server
(on git.centos.org)

Is that possible to  have an overview of the infra and goals (aka the
architecture) of this GSoC doc project ? that would help
understanding, as I agree that I'm currently lost, and I'm probably
not the only one, also the reason for that thread :-)

- -- 

Fabian Arrotin
The CentOS Project | http://www.centos.org
gpg key: 56BEC54E | twitter: @arrfab
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iEYEARECAAYFAlW/xmUACgkQnVkHo1a+xU6ylQCgml2UgH9Q9DuRczbdZNqedudw
yTQAn0NvZtyfNgCyhnvE/OifBXC62CLw
=vV7K
-----END PGP SIGNATURE-----