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

Thu Mar 12 21:59:56 UTC 2015

-----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-----