Reworking Docs

Table of Contents

In May of this year the docs team, with the help of some great folks from Red Hat
and the CentOS project held a Documentation FAD. During that event we discussed a lot of important
topics including the docs team's publishing toolchain, and the barrier to entry that is
docbook.

Over the course of the FAD, and after creating a lot of User Stories, the group came to the
following conclusions:

We need to find ways to help enable community members contribute to documentation

Sharing documentation with Red Hat Content Services is good for everyone

This lead us to create a complex requirements matrix that Remy did his best at capturing
online, leading to the conclusion that the best solution is to keep with a static publishing
toolchain that supports a less user hostile markup language.

To that end the team suggested that we use Shaun McCance's2Pintail for publishing, AsciiDoc
as the markup language, and a new format for our documentation. The most common question about
all of this is "Why?" and the easy answer is that they had the best results against the
requirements, but I hope to give a little more insight into that.

1 Pintail

Publican has been great for the Fedora Docs team of the years, but its real strength is in
docbook based full length docs, and that is not want the docs teams is trying to write anymore.
When coupled with the fact that the site is generated with an extremely old version of
Publican, last supported on Fedora ~18, it was time for us to move on.

Pintail, fits the build, because it is simple to use, a simple code base, and well supported by
a responsive upstream. Being written in Python means that members of the Docs Team, and the
Fedora community at large, are already able to troubleshoot and fix bugs; something that was
not easy to do with Publican. Additional, Shaun has been extremely helpful showing us the ropes
and working on feature requests that are only needed by Fedora.

Finally, the tool supports our current and future markdown languages, more on why this is
important in a bit.

2 Asciidoc

Markdown is probably the most popular markup language around right now, but for a
documentation project it is missing a lot of features and because of that many "flavors" of
markdown exist. The issue is simple, markdown was not designed for writing documentation
it was developed so that its creator did not have to write HTML tags. This means that it
lacks support for many of the structural elements that make good documentation great. Asciidoc
was built to support everything that makes docbook great, while keeping users from endlessly
writing <tags>.3

The fact that it is a great markup language for documentation was only one part of the
reasoning, it turns out that Red Hat is starting to move more and more towards AsciiDoc as
well, and using the same markup will help the teams collaborate that much easier. So while
AsiiDoc many not be the most popular markup language on the planet, and it still may have a
learning curve for some users, it fits the needs of our documentation better than the
alternatives.

3 New Format

Books are great, everyone reads them (or at least did in school), but they are hard to write
and harder to maintain. So we are not going to write them any more, instead smaller single page
topic based documents will be written that can be grouped into collections of a larger topic.

For example, a page may be written about disk formatting and be included in a collection about
system configuration, but that same topic could also be reused in another collection where
formatting a disk is something that needs done. This will not only help to reduce the amount
of documentation that the team needs to maintain, but it will once again allow us to share
content with Red Hat more easily.

4 The Plan

All of this is a lot of work. Any one of the sections above is a lot of work, but when you
put it all together it is a great deal more. Waiting for everything to be complete would mean
that we would not see the fruits of this plan for at least a year, but in reality it would
probably be several years. Since fruit is good, as it motivates all of us to keep working,
the plan is to work on this in phases.

Once that is done, we will start the long process of rewriting documents to fit the new style,
using AsciiDoc rather than docbook, publishing new collections of topics as the team decides
that they are ready to publish. That will mean for a period of time we will have both styles of
docs on the site, but it also means that we can focus on writing new documentation without
having to also work on all of the old style docs for every release until we are done.

5 Help Wanted

As mentioned before this is a big project, and we need help. Everything from design and
engineering to writing. If you want to help join us in #fedora-docs or take a look at
the tracking ticket for phase one on Pagure.