5 reasons to use a rendered language for documentation
In a previous article, I gave 5 reasons why wikis are great for documentation. It was a big deception. Truth be told, I’m not a big fan of wikis for the most part. So today I present to you 5 reasons to use a rendered language to publish your documentation.
What does mean 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 command. Wikis also technically produce rendered documents, but I’m talking about something decoupled from the publishing platform. Now that we’ve cleared up the vocabulary, let’s look at the reasons:
- Rendered documents offer greater formatting flexibility. This varies by language, but generally you can distinguish command names from screen output with something more granular than a combination of bold, italic, and monospaced text.
- The documents submitted impose a certain structure. With piles of loose documentation, it can be difficult to progress from one step to the next. Because nothing came before, concepts either have to be re-explained on many pages, or the reader has to wade through a rabbit hole of links. By encouraging a bit of structure, rendered languages cause the writer to consider how the words flow and how the reader will consume them.
- Rendered documents are portable to other formats. Most often, documents are produced in HTML and PDF form; however, publishing to EPUB or another reader format is just one argument. This, together with the previous point, also means that those who wish to have a printed copy of the documentation can do so.
- Rendered documents integrate seamlessly with code in your version control system. This means all the usual benefits: distributed editing, branching for different versions, automatic building with continuous integration, etc.
- The returned documents can be self-contained. In offline or low-bandwidth situations, documents that can be read from the local disk are necessary.
Make 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 best suited for rendered documents.
Having a team of dedicated documentation writers is also helpful. Most markup languages and tools used to produce documents have a higher barrier to entry than a wiki. Occasional contributions are much harder to receive, and even dedicated potential contributors may be discouraged by the steeper learning curve.
If you choose to use rendered documents as your format of choice, then you must choose 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 [email protected]