[CentOS-docs] Docs strategy and tactics [RFC]

[Shaun McCance]

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