Reworking Docs

Posted on by Zach Oglesby
Tags: fedora

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:

  1. We need to find ways to help enable community members contribute to documentation
  2. Sharing documentation with Red Hat Content Services is good for everyone
  3. The current Publican setup is not meeting our needs
  4. Most people dislike1 docbook

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's2 Pintail 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.

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.

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.

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.

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.

The first phase will be the implementation of Pintail and a system for continuous integration and delivery. This means that once the new site is ready we will begin to use it to publish the current docbook books that are on docs.fedoraproject.org right now.

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.

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.


  1. Hate is probably just as accurate

  2. He may prefer we refer to it as Project Mallard's Pintail

  3. After thinking about it Sparks and I had the same conversation about this at FUDCon Lawrence in 2013.