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