5 reasons to use a rendered language for documentation

In a previous post, I gave 5 reasons wikis rock for documentation. It was a great deceit. In truth, I'm not a big fan of wikis in most cases. So today I present 5 reasons to use a rendered language to publish your documentation.

What does rendered document mean? Essentially, it means not a wiki. Instead, you write the content in your favorite text editor and then turn it into a publishable document by some command. Wikis technically produce rendered documents, too, but I'm talking about something decoupled from the publishing platform. Now that we have the vocabulary cleared up, let's take a look at the reasons:

1. Rendered documents offer more formatting flexibility. This varies by language, but generally you can distinguish command names from screen ouput with something more granular than some combination of bold, italic, and monospaced text.
2. Rendered documents enforce some structure. With loose piles of documentation, progressing through steps can be hard. Because nothing came before, concepts either need to be re-explained on many pages or the reader has to go down a rabbit hole of links. By encouraging a little bit of structure, rendered languages make the writer give consideration to how the words flow and how the reader will consume them.
3. Rendered documents are portable to other formats. Most often, documents are produced in HTML and PDF forms; however, publishing to EPUB or other reader format is just an argument away. This, along with the previous point, also means that those who want to have a print copy of the documentation can do so.
4. Rendered documents fit neatly alongside the code in your version control system. This means all of the usual benefits: distributed editing, branching for different versions, automatic building with continuous integration, and so on.
5. Rendered documents can stand alone. In offline or low-bandwidth situations, documents that can be read from local disk are necessary.

Making the decision

The careful reader will have noticed that some of these benefits also apply to wikis, and some of the benefits are not universally applicable. The right technology for your project depends on the nature of your project and your community. Stable projects with defined release cycles are the best fit for rendered documents.

Having a team of dedicated documentation writers is helpful as well. Most markup languages and tools used to produce the documents have a higher barrier to entry than a wiki. Casual contributions are much harder to receive, and even dedicated would-be contributors can be discouraged by the steeper learning curve.

If you choose to go with rendered documents as your format of choice, you then have to pick a markup language. But that's a topic for another day.

This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at open@opensource.com.