5 reasons to use a rendered language for documentation

Register or Login to like
pink typewriter

Original photo by Marco Tedaldi. Modified by Rikki Endsley. CC BY-SA 2.0.

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.

Doc
Dish

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.

Ben Cotton is a meteorologist by training, but weather makes a great hobby. Ben works as the Fedora Program Manager at Red Hat. He co-founded a local open source meetup group, and is a member of the Open Source Initiative and a supporter of Software Freedom Conservancy. Find him on Twitter (@FunnelFiasco) or at FunnelFiasco.com.

3 Comments

Long ago, I contributed a "mini-howto" to the Linux Documentation project. They accepted it in plain text. It supplemented a 60-page reference written in LaTeX. Shortly after that, the LDP stopped accepting plain text, and insisted on a markup language called Docbook. The Docbook toolchain was seriously broken. More than half the documents in LDP froze after that, because their authors weren't interested in dicking around with Docbook to try to get it working. LDP is pretty much abandoned these days. i think Docbook was the decision that killed it.

Docbook was the wrong choice for a single-source doc format. But single source is still a good idea. These days I would advise LibreOffice Writer, which can render to anything. (You just have to stick scrupulously to character and paragraph styles for all formatting. No one-off markups.) LaTeX (and Metafont) were a lot of fun to play around with, but they can be a real time sink.

DocBook is extremely heavy for something like that. You should take a good look at Markdown and it's various incarnations. It would be a shame to write off the rendered space because of a poor experience with a heavy language.

In reply to by Celyle (not verified)

I have to say that Markdown as a markup language is much easier to use (and learn) than wiki. Of course, it does not have a fancy graphical interface, but every command is as easy as it can get.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.