-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 I've been thinking for a little while, and talking with people, about what would be a good documentation strategy for the CentOS Project. == tl;dnr aka Summary This is a proposal around creating new, short-format documentation about doing cool new things on top of CentOS Linux. These docs would support the work of the various SIGs (Cloud, Storage, Virt, etc.), in some cases living in the upstream project and rebuilt in to CentOS by SIGs. == Overview When it comes to all the documentation we can think about, there are several areas with clear importance: 1. Base CentOS Linux materials, which are numerous and include the upstream RHEL documentation set. These are focused on installation, configuration, and administration of various parts of a CentOS Linux instance or set of instances. 2. Doing cool things on top of CentOS Linux. 3. Content for working within the project, such as part of a SIG, how to ask questions on IRC, and how to conduct oneself on mailing lists. For item 3, we have some fairly robust and growing content, and I think that can continue to grow somewhat organically. We may want to adopt tooling and workflow from this proposal as it matures. For item 1, we are currently blocked from moving ahead by not being able to easily rebrand and reuse the RHEL doc set without the XML sources. Reworking external content is also an idea, but a similar pain for different reasons. I want to set aside this item for the purposes of this thread. Item 2 is the one where we can get some great traction: * Content that shows how to do things on top CentOS Linux is key for adoption of new use cases. * It's an area where we can lower the barriers to contribution greatly. * Many upstream projects can benefit from better content on how to use their software on CentOS Linux, and the Project benefits from the shared exposure. The below strategy proposal is focused around item 2. ## BEGIN PROPOSAL "You've just installed CentOS Linux, great, congratulations -- you now have an expensive heater. What people need is content on how to /do something/ with that installation." -- Jim Perrin == Overview The overall idea is two basic parts: 1. Focus on short-form, how-to/tutorial content. In many cases, multiple docs/articles are linked together to show the various steps. For example, these ARMv8 posts from Jim: http://seven.centos.org/2015/03/centos-linux-7-and-arm/ http://seven.centos.org/2015/03/building-centos-linux-7-for-armv8/ 2. Docs that are about combining an upstream (usually via a SIG) either i) live in the upstream repo and are rebuilt in to CentOS, or ii) live in CentOS but are shared/socialized into the upstream project and its ecosystem. Goal here is to minimize our own ongoing maintenance by following the same "upstream first, carry minimal patches" philosophy that goes in to the way Fedora is built and RHEL is maintained. This is an example of an upstream we could contribute in to, using OpenShift Origin on top of CentOS Linux: https://blog.openshift.com/new-platform-new-docs-part/ A workflow might go like this; this is deliberately tooling unspecific, more on tools below. 1. A person has an idea, a draft, or polished piece of content that is about doing something with CentOS Linux. If properly licensed, it can be from an outside person brought in to the Project by one of us. (I.e., you find a great how-to licensed CC BY SA.) 2. Content is brought to centos-docs at centos.org for review of the next step. 3. CentOS Docs SIG[1] reviews and decides next approach: 3.1 If the doc is CentOS Linux or Project specific, canonical source goes to git.centos.org & is published to centos.org/docs. It may require conversion to the preferred source format for building as a doc. 3.2 If the doc fits perfectly within an upstream as an example of how to deploy or use the upstream software on the CentOS platform, we push doc to the appropriate upstream(s). Link or copy is carried at centos.org/docs and appropriate wiki pages. 3.3 Unclear where doc fits, so author and SIG members engage with upstream project(s) to find out best way forward. 3.3.1 Write down each upstream preference as we learn. 4. Content is prepared for target location and delivered. 4.1 Document is edited for style, grammar, punctuation, etc. 4.2 Document is edited for ease of translation. 4.3 Conversion to a standard format, if required. 4.4 Check-in to version controlled system. 5. Publicity around document being available -- @centos, proper links across CentOS wiki and at /docs, possibly a blog post highlighting a new series of content, etc. 5.1 Potential interaction with Promo SIG here. == Tooling There are a few levels to think about here where it comes to thinking about a chunk of content: A. The markup used, standards around how it's written (avoid idioms, use the Oxford comma, etc.) B. Tools for editing that don't drive people crazy. C. Tools to convert the source to one or more document formats. This includes converting to an upstream project's preferred format. Without getting too far ahead here, there are clearly a handful of solutions that will work well. For example, we could author using whatever preferred editor in a markup such as AsciiDoc or MarkDown, then use e.g. AsciiDoctor to do the conversions (to Mallard, XML, HTML, PDF, ePub, etc.), all with sources stored in Git. That would allow for us to mirror content to github.com/CentOS and people could use Prose.io for editing and pull requests to submit content. We would sync all that back to git.centos.org. That sort of workflow and tooling would allow us to take advantage of the 'social coding' aspect of GitHub, which is essentially a very low barrier to writing that is missing in tools such as DocBook XML. == Notes [1] We have to write up a secondary proposal for the CentOS Board to make the Docs group a SIG. Part of the SIG idea is to have 'functional SIGs', meaning groups whose purpose is to get things done /for/ the Project itself. Examples are Infrastructure, Documentation, Design, Promotions (Marketing), CBS/Build System, and so forth. These are different from 'upstream or variant SIGs' that focus on doing things /on/ the Project's artifacts, for example the Cloud Instance SIG, Virt SIG, and Cloud SIG. ## END PROPOSAL 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 v1 iEYEARECAAYFAlUCDFwACgkQ2ZIOBq0ODEHq8gCgnl23i+wJesEfLimjOR+e1hkc pZUAoLKIMDuSmHRadHE3Cqu4w0mpB69d =DcIS -----END PGP SIGNATURE-----
On Thu, 2015-03-12 at 14:59 -0700, Karsten Wade wrote:> I've been thinking for a little while, and talking with people, about > what would be a good documentation strategy for the CentOS Project. > > == tl;dnr aka Summary > > This is a proposal around creating new, short-format > documentation about doing cool new things on top of CentOS > Linux. These docs would support the work of the various SIGs (Cloud, > Storage, Virt, etc.), in some cases living in the upstream project and > rebuilt in to CentOS by SIGs.I like everything you've written. But comments inline below anyway.> == Overview > > When it comes to all the documentation we can think about, there are > several areas with clear importance: > > 1. Base CentOS Linux materials, which are numerous and include the > upstream RHEL documentation set. These are focused on installation, > configuration, and administration of various parts of a CentOS Linux > instance or set of instances. > > 2. Doing cool things on top of CentOS Linux. > > 3. Content for working within the project, such as part of a SIG, how to > ask questions on IRC, and how to conduct oneself on mailing lists. > > For item 3, we have some fairly robust and growing content, and I think > that can continue to grow somewhat organically. We may want to adopt > tooling and workflow from this proposal as it matures. > > For item 1, we are currently blocked from moving ahead by not being > able to easily rebrand and reuse the RHEL doc set without the XML > sources. Reworking external content is also an idea, but a similar > pain for different reasons. I want to set aside this item for the > purposes of this thread. > > Item 2 is the one where we can get some great traction:I like putting focus on this. It provides people a resource for things they actually want to do. Nobody wants just an operating system. I also think it's a great avenue for getting community contributions. It's easy to make a one-time contribution on a topic you know well without digging into how it affects everything. An anecdote: I pay Linode for a VPS. I run a few things on there that I'm only barely qualified to run. The Linode docs have some of the best guides I've seen for things like setting up Postfix and Mailman to run a mailing list. It's not docs for Linode per se, but it is docs for what you actually want to do once you've paid for that shiny VPS. I think there's a lot of potential here for CentOS to be the source for setup guides and the like for stuff people actually do once they've installed an enterprise OS.> * Content that shows how to do things on top CentOS Linux is key for > adoption of new use cases. > * It's an area where we can lower the barriers to contribution greatly. > * Many upstream projects can benefit from better content on how to use > their software on CentOS Linux, and the Project benefits from the shared > exposure. > > The below strategy proposal is focused around item 2. > > ## BEGIN PROPOSAL > > "You've just installed CentOS Linux, great, congratulations -- you > now have an expensive heater. What people need is content on how to > /do something/ with that installation." > > -- Jim Perrin > > == Overview > > The overall idea is two basic parts: > > 1. Focus on short-form, how-to/tutorial content. In many cases, multiple > docs/articles are linked together to show the various steps. For > example, these ARMv8 posts from Jim: > > http://seven.centos.org/2015/03/centos-linux-7-and-arm/ > http://seven.centos.org/2015/03/building-centos-linux-7-for-armv8/Agreed. But make sure it's easy to submit independent content without worrying too much about how it fits into a larger narrative. Narratives are blockers to contribution.> 2. Docs that are about combining an upstream (usually via a SIG) either > i) live in the upstream repo and are rebuilt in to CentOS, or ii) live > in CentOS but are shared/socialized into the upstream project and its > ecosystem. > > Goal here is to minimize our own ongoing maintenance by following the > same "upstream first, carry minimal patches" philosophy that goes in to > the way Fedora is built and RHEL is maintained. > > This is an example of an upstream we could contribute in to, using > OpenShift Origin on top of CentOS Linux: > > https://blog.openshift.com/new-platform-new-docs-part/ > > A workflow might go like this; this is deliberately tooling unspecific, > more on tools below. > > 1. A person has an idea, a draft, or polished piece of content that is > about doing something with CentOS Linux. If properly licensed, it can > be from an outside person brought in to the Project by one of us. > (I.e., you find a great how-to licensed CC BY SA.) > > 2. Content is brought to centos-docs at centos.org for review of the next > step. > > 3. CentOS Docs SIG[1] reviews and decides next approach: > > 3.1 If the doc is CentOS Linux or Project specific, canonical source > goes to git.centos.org & is published to centos.org/docs. It may require > conversion to the preferred source format for building as a doc. > > 3.2 If the doc fits perfectly within an upstream as an example of > how to deploy or use the upstream software on the CentOS platform, we > push doc to the appropriate upstream(s). Link or copy is carried at > centos.org/docs and appropriate wiki pages. > > 3.3 Unclear where doc fits, so author and SIG members engage with > upstream project(s) to find out best way forward.One of the reasons this might be the case is that the doc deals with integration, so there are multiple upstreams involved. And I think that's an area where CentOS docs can provide real value, and drive traffic to CentOS. I want a Google search for "How to deploy X with Y" to give a CentOS result.> 3.3.1 Write down each upstream preference as we learn. > > 4. Content is prepared for target location and delivered. > > 4.1 Document is edited for style, grammar, punctuation, etc. > > 4.2 Document is edited for ease of translation. > > 4.3 Conversion to a standard format, if required. > > 4.4 Check-in to version controlled system. > > 5. Publicity around document being available -- @centos, proper links > across CentOS wiki and at /docs, possibly a blog post highlighting a new > series of content, etc. > > 5.1 Potential interaction with Promo SIG here. > > == Tooling > > There are a few levels to think about here where it comes to thinking > about a chunk of content: > > A. The markup used, standards around how it's written (avoid idioms, > use the Oxford comma, etc.)Don't make contributors work too hard at this. Nitpicky review processes are a huge barrier to contribution, and not just for newcomers. I've tried a few times over the last few years to kickstart an open source style guide that projects could share, so we don't all have to keep writing our own. What I think I've learned is that you do want a style guide, but you really ought to have a tl;dr version. Sort of like codes of conducts often have short forms and long forms. Nobody wants to read the long form before making their first contribution.> B. Tools for editing that don't drive people crazy. > > C. Tools to convert the source to one or more document formats. This > includes converting to an upstream project's preferred format. > > Without getting too far ahead here, there are clearly a handful of > solutions that will work well. > > For example, we could author using whatever preferred editor in a > markup such as AsciiDoc or MarkDown, then use e.g. AsciiDoctor to do > the conversions (to Mallard, XML, HTML, PDF, ePub, etc.), all with > sources stored in Git. > > That would allow for us to mirror content to github.com/CentOS and > people could use Prose.io for editing and pull requests to submit > content. We would sync all that back to git.centos.org. > > That sort of workflow and tooling would allow us to take advantage of > the 'social coding' aspect of GitHub, which is essentially a very low > barrier to writing that is missing in tools such as DocBook XML.For editing, the GitHub workflow is nice in that it allows me to use my preferred editor and other tools, but also allows super-easy editing on the web. Prose.io is a nice idea, but I haven't found it very compelling in practice. You need tools for maintenance of very large sets of docs. For smaller sets, you can deal with a lot more person work. It sounds like you want to set up content pools that multiple projects and upstreams can pull from. That's a very hard problem, and even harder if you need to support multiple formats. The technical details of such a system could easily take up another email thread.> == Notes > > [1] We have to write up a secondary proposal for the CentOS Board to > make the Docs group a SIG. Part of the SIG idea is to have 'functional > SIGs', meaning groups whose purpose is to get things done /for/ the > Project itself. Examples are Infrastructure, Documentation, Design, > Promotions (Marketing), CBS/Build System, and so forth. These are > different from 'upstream or variant SIGs' that focus on doing things > /on/ the Project's artifacts, for example the Cloud Instance SIG, Virt > SIG, and Cloud SIG.+1 -- Shaun
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 03/12/2015 04:59 PM, Karsten Wade wrote: <much snipping>> That would allow for us to mirror content to github.com/CentOS and > people could use Prose.io for editing and pull requests to submit > content. We would sync all that back to git.centos.org. >The last I looked at Prose.io, it wanted more privilege than I was comfortable giving it. That said, keeping docs in git (and leveraging github for drive-by contributions) allows us to validate pull requests for documentation and version the documents in a sane fashion. I'm in favor of this aspect. My only question is, how do we determine what goes in the wiki vs what goes in git? The flow/format between the two is a bit different. Or is this development the first step in the transition away from the wiki to another medium? - -- Jim Perrin The CentOS Project | http://www.centos.org twitter: @BitIntegrity | GPG Key: FA09AD77 -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.22 (GNU/Linux) iQIcBAEBAgAGBQJVByHhAAoJEBbHyC76Ca13+NAP/1mwXQdV9sPTl2CCTUBQ3zze lgyAlo8fP2oQqjdXgWzFFG6guYjK5Lepp1/hzo1uSPXdQ0qUTUTRE+8O5jTaAoBE TS5IrrJRfeoDSoZkdCqGjrz974JU6feWuEbbdi7E7JVnQFqSzCS7MIccw66VN/YH AUezk1939ByqWntK/aN7r7iFz4U7OFOUXq8GrOnPc7ktKwrsv8xUrdhXOY6w15lA 4ccApVy1fK9RNJNMZHFPfSXCWBDkXco9vOTg2XUIgF8fC27CKSAbumnI0mAYo+Ue Hz4BUAdZOx1PG5Zhh9MCsiCZ6xkia7piIfHu6hD8G955c5JH3KnzSBmCRPaHxbv7 XX7sBJwR66LMI1RwWH4yfSuQQ3shhp9r2kxkPpNhB7bj70qR4/oQcOJSkwTV2OtR mjM7hOXh5wGRWCbsJajQ+bYBnEMHLUWhGWg1oaeWWhhF7sutsSCqgwVcS4bVCu8i uQyvhxgIJhJZWfFR2jTgoJgrMHwceoSjBS9K8DLEmWqu5edpIk/xoPSiWuwDfU46 auSqtYBfPztPLKvmq6gzkR/YniFZXdCLSyP/nowbsnoDkKoveNnh42bRGybM7ckg j0UL2Uxk3C+EOd1AMiFNNqRoDVy0+WsfwOwFJsSif3JjXJtXwHKjEnkPf2k2cSFD XoictwEmTJH50dzI9DOS =C+5k -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 03/16/2015 11:33 AM, Jim Perrin wrote:> My only question is, how do we determine what goes in the wiki vs > what goes in git? The flow/format between the two is a bit > different. Or is this development the first step in the transition > away from the wiki to another medium?That's a good question, and I don't have it answered. :) It has to do with our intention/thinking as a group. I don't see a reason to move away from the wiki as a contributor-focused area, for example. It self-organizes fairly well, and when people need to write something easily-enough at a centos.org domain it lets folks do that fairly well. But I'm picking a fairly-small focus area (docs for contributors), as we'll have to add people to the wiki, curate the content a bit, etc. This is why I'm thinking the short-form how-to-do-stuff-on-CentOS is a chance to break away from the wiki with a new, lower-barriers toolset and process without having to deal with "should we wiki or should we not?" - - 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 v1 iEYEARECAAYFAlUHMq8ACgkQ2ZIOBq0ODEFVLQCgxmiVkcnoBLfF59UTDkwIeGX3 nxEAoMuNEdj/piEQ8VmSO6smbFNHUNYF =6zZE -----END PGP SIGNATURE-----
> On Mon, Mar 16, 2015 at 10:48 PM, Shaun McCance <shaunm at redhat.com> wrote: > I like putting focus on this. It provides people a resource for things > they actually want to do. Nobody wants just an operating system. I also > think it's a great avenue for getting community contributions. It's easy > to make a one-time contribution on a topic you know well without digging > into how it affects everything. > > An anecdote: I pay Linode for a VPS. I run a few things on there that > I'm only barely qualified to run. The Linode docs have some of the best > guides I've seen for things like setting up Postfix and Mailman to run a > mailing list. It's not docs for Linode per se, but it is docs for what > you actually want to do once you've paid for that shiny VPS. > > I think there's a lot of potential here for CentOS to be the source for > setup guides and the like for stuff people actually do once they've > installed an enterprise OS.This is one of the main motivation about this. Curating content from contributors which write about how to do things on CentOS. When I get a new shiny OS, I need to know how powerful it is, what I can do with it. I have a VPS on digitalocean. The reason I got convinced of using a VPS was their documentation. How awesome a VPS is, what I can do with it. Their docs is selling their product!> > One of the reasons this might be the case is that the doc deals with > integration, so there are multiple upstreams involved. And I think > that's an area where CentOS docs can provide real value, and drive > traffic to CentOS. I want a Google search for "How to deploy X with Y" > to give a CentOS result. >In my initial discussion with Karsten, we discussed about this. Right now if I have to setup or deploy X on Y, I google it, I find lots of content but they are scattered over the internet. We try them, not knowing whether they'll work perfectly or not. The new approach changes this. There will be curated content on one central place.> For editing, the GitHub workflow is nice in that it allows me to use my > preferred editor and other tools, but also allows super-easy editing on > the web. Prose.io is a nice idea, but I haven't found it very compelling > in practice. > > You need tools for maintenance of very large sets of docs. For smaller > sets, you can deal with a lot more person work. > > It sounds like you want to set up content pools that multiple projects > and upstreams can pull from. That's a very hard problem, and even harder > if you need to support multiple formats. The technical details of such a > system could easily take up another email thread.That's the goal. Start a new project on this. A new toolchain. It will take time to develop it fully. There is interest of me taking this as Google Summer of Code Project with Karsten as mentor. My knowledge is very limited, so pardon me if sounds stupid. Regards, Kunaal Jain
On 03/12/2015 03:59 PM, Karsten Wade wrote:> I've been thinking for a little while, and talking with people, about > what would be a good documentation strategy for the CentOS Project. > > == tl;dnr aka Summary > > This is a proposal around creating new, short-format > documentation about doing cool new things on top of CentOS > Linux. These docs would support the work of the various SIGs (Cloud, > Storage, Virt, etc.), in some cases living in the upstream project and > rebuilt in to CentOS by SIGs. > > == Overview > > When it comes to all the documentation we can think about, there are > several areas with clear importance: > > 1. Base CentOS Linux materials, which are numerous and include the > upstream RHEL documentation set. These are focused on installation, > configuration, and administration of various parts of a CentOS Linux > instance or set of instances. > > 2. Doing cool things on top of CentOS Linux. > > 3. Content for working within the project, such as part of a SIG, how to > ask questions on IRC, and how to conduct oneself on mailing lists. > > For item 3, we have some fairly robust and growing content, and I think > that can continue to grow somewhat organically. We may want to adopt > tooling and workflow from this proposal as it matures. > > For item 1, we are currently blocked from moving ahead by not being > able to easily rebrand and reuse the RHEL doc set without the XML > sources. Reworking external content is also an idea, but a similar > pain for different reasons. I want to set aside this item for the > purposes of this thread. > > Item 2 is the one where we can get some great traction: > > * Content that shows how to do things on top CentOS Linux is key for > adoption of new use cases. > * It's an area where we can lower the barriers to contribution greatly. > * Many upstream projects can benefit from better content on how to use > their software on CentOS Linux, and the Project benefits from the shared > exposure. > > The below strategy proposal is focused around item 2. > > ## BEGIN PROPOSAL > > "You've just installed CentOS Linux, great, congratulations -- you > now have an expensive heater. What people need is content on how to > /do something/ with that installation." > > -- Jim Perrin > > == Overview > > The overall idea is two basic parts: > > 1. Focus on short-form, how-to/tutorial content. In many cases, multiple > docs/articles are linked together to show the various steps. For > example, these ARMv8 posts from Jim: > > http://seven.centos.org/2015/03/centos-linux-7-and-arm/ > http://seven.centos.org/2015/03/building-centos-linux-7-for-armv8/ > > 2. Docs that are about combining an upstream (usually via a SIG) either > i) live in the upstream repo and are rebuilt in to CentOS, or ii) live > in CentOS but are shared/socialized into the upstream project and its > ecosystem. > > Goal here is to minimize our own ongoing maintenance by following the > same "upstream first, carry minimal patches" philosophy that goes in to > the way Fedora is built and RHEL is maintained. > > This is an example of an upstream we could contribute in to, using > OpenShift Origin on top of CentOS Linux: > > https://blog.openshift.com/new-platform-new-docs-part/ > > A workflow might go like this; this is deliberately tooling unspecific, > more on tools below. > > 1. A person has an idea, a draft, or polished piece of content that is > about doing something with CentOS Linux. If properly licensed, it can > be from an outside person brought in to the Project by one of us. > (I.e., you find a great how-to licensed CC BY SA.) > > 2. Content is brought to centos-docs at centos.org for review of the next > step. > > 3. CentOS Docs SIG[1] reviews and decides next approach: > > 3.1 If the doc is CentOS Linux or Project specific, canonical source > goes to git.centos.org & is published to centos.org/docs. It may require > conversion to the preferred source format for building as a doc. > > 3.2 If the doc fits perfectly within an upstream as an example of > how to deploy or use the upstream software on the CentOS platform, we > push doc to the appropriate upstream(s). Link or copy is carried at > centos.org/docs and appropriate wiki pages. > > 3.3 Unclear where doc fits, so author and SIG members engage with > upstream project(s) to find out best way forward. > > 3.3.1 Write down each upstream preference as we learn. > > 4. Content is prepared for target location and delivered. > > 4.1 Document is edited for style, grammar, punctuation, etc. > > 4.2 Document is edited for ease of translation. > > 4.3 Conversion to a standard format, if required. > > 4.4 Check-in to version controlled system. > > 5. Publicity around document being available -- @centos, proper links > across CentOS wiki and at /docs, possibly a blog post highlighting a new > series of content, etc. > > 5.1 Potential interaction with Promo SIG here. > > == Tooling > > There are a few levels to think about here where it comes to thinking > about a chunk of content: > > A. The markup used, standards around how it's written (avoid idioms, > use the Oxford comma, etc.) > > B. Tools for editing that don't drive people crazy. > > C. Tools to convert the source to one or more document formats. This > includes converting to an upstream project's preferred format. > > Without getting too far ahead here, there are clearly a handful of > solutions that will work well. > > For example, we could author using whatever preferred editor in a > markup such as AsciiDoc or MarkDown, then use e.g. AsciiDoctor to do > the conversions (to Mallard, XML, HTML, PDF, ePub, etc.), all with > sources stored in Git. > > That would allow for us to mirror content to github.com/CentOS and > people could use Prose.io for editing and pull requests to submit > content. We would sync all that back to git.centos.org. > > That sort of workflow and tooling would allow us to take advantage of > the 'social coding' aspect of GitHub, which is essentially a very low > barrier to writing that is missing in tools such as DocBook XML. > > == Notes > > [1] We have to write up a secondary proposal for the CentOS Board to > make the Docs group a SIG. Part of the SIG idea is to have 'functional > SIGs', meaning groups whose purpose is to get things done /for/ the > Project itself. Examples are Infrastructure, Documentation, Design, > Promotions (Marketing), CBS/Build System, and so forth. These are > different from 'upstream or variant SIGs' that focus on doing things > /on/ the Project's artifacts, for example the Cloud Instance SIG, Virt > SIG, and Cloud SIG. > > ## END PROPOSAL > > Regards, > > - KarstenWe've been having a very similar conversation in the Fedora Docs group. I have a crude plan for the tooling part, to extend buildbot to address this; the idea is that you feed it git repos containing documentation in whatever supported format, some metadata is extracted, the content is built to html, then a navigation portal is built using the extracted metadata. Bonus, continuous integration of translations from Zanata or Transifex can be built in too. Changes are triggered by commit polling, the operating theory is that you'll have some branches of a repo designated for production/publishing, one might be the 'official prelease drafts', the rest just get validation. Right now, this is just an ansible playground living at https://github.com/immanetize/anerist/tree/ansible but I intent to cludge together python modules to extend the buildbot BuildFactory class so it's a proper redistributable thing instead of a massive master.cfg . If it sounds interesting to you, I'm sure the effort could benefit from the involvement of people with more expertise. -- -- Pete
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 03/16/2015 04:05 PM, Pete Travis wrote:> We've been having a very similar conversation in the Fedora Docs > group. I have a crude plan for the tooling part, to extend > buildbot to address this; the idea is that you feed it git repos > containing documentation in whatever supported format, some > metadata is extracted, the content is built to html, then a > navigation portal is built using the extracted metadata. Bonus, > continuous integration of translations from Zanata or Transifex can > be built in too. Changes are triggered by commit polling, the > operating theory is that you'll have some branches of a repo > designated for production/publishing, one might be the 'official > prelease drafts', the rest just get validation. > > Right now, this is just an ansible playground living at > https://github.com/immanetize/anerist/tree/ansible but I intent to > cludge together python modules to extend the buildbot BuildFactory > class so it's a proper redistributable thing instead of a massive > master.cfg . If it sounds interesting to you, I'm sure the effort > could benefit from the involvement of people with more expertise.Not surprising that we're approaching similar solutions from different directions, as my community docs DNA and experience is rooted in the Fedora Project. (Or you could say I'm partially to blame for how things got the way they are in Fedora, and want to save such mistakes on the CentOS Docs side. :) ) Let's definitely see if we can craft solution vectors that approach a common point. I like your CI approach overall, it layers nicely on top of what I proposed. (I also didn't address translations other than in style, but I think CentOS Project will quickly want to get there.) 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 v1 iEYEARECAAYFAlUHfYMACgkQ2ZIOBq0ODEFJhQCcDcUaxBITmOC+7VAPJxCvzRqm 6uoAnj/s+kVok7jrosc2IkrvRHhVFtDv =Kihy -----END PGP SIGNATURE-----