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, > > - Karsten 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. -- -- Pete