When I ended my Doc Dish article about why you should use a rendered language for documentation, I told you that selecting a language was a matter for another day.
Well another day has finally arrived.
There's no shortage of languages you can use for formatting and publishing your documentation, and your choice of language will depend on your project's needs. In this article I'll look at several different language options, ranging from the simplest to the most complex. It's hardly an exhaustive list, so make the case for your favorite (or most hated) language in the comments.
Markdown
Markdown is one of the simplest markup languages available. In source form, it's very similar to plain text, which makes it easy to follow without being rendered. Anyone familiar with wiki syntax or IRC/instant messaging conventions will find it easy to use. Hosting services like GitHub will automatically render Markdown files when browsing code repositories, which makes Markdown ideal for README files and similar content.
This simplicity, however, means a lack of flexibility. Distinguishing different kinds of text (without throwing in a bunch of HTML) can be difficult. There are also a variety of Markdown implementations and derivatives (e.g. CommonMark) since the standard is not clearly defined. If you're using Markdown for your project, you should identify the implementation and tool(s) that you expect contributors to use.
reStructured Text
reStructured Text (RST or reST) is similar to Markdown in that it's nearly plain text in source form. Originally developed as a Python tool, reStructured Text now enjoys wide use in technical documentation, particularly in combination with the Sphinx rendering system.
Developers appreciate the language's lightweight markup. Despite this, however, reStructured Text has the flexibility to produce nice-looking documentation. Project hosting services will generally render reStructured Text files in the browser (again making it suitable for READMEs). Unlike Markdown, reStructured Text does have a defined specification.
DocBook
Here's where things get more complex.
DocBook is an XML specification designed for technical documentation. Just the mere mention of XML is enough to send some people running for the hills, but the flexibility it provides can be a compelling argument, especially for user documentation.
In combination with tools like Publican, it can render excellent-looking documentation in a variety of formats. Red Hat and Fedora use DocBook for guides and other long-form documentation
DocBook has elements for GUI items and actions, text commands, and many other common technical concepts. With Publican, you can publish your docs to a branded website. While DocBook's source code can be a little rough on the eyes, the language offers a great deal of power and flexibility in formatting.
LaTeX
And then there's LaTeX.
LaTeX is a powerful typesetting language that works particularly well for mathematical equations. Some academically-based projects use it for this reason. However, LaTeX has a very steep learning curve. Its aesthetic appeal leaves something to be desired as well.
Making your choice
So which of these (or other) options will you choose?
Your answer to this question will depend on what your contributors and potential contributors are comfortable with and what kind of documentation you're going to produce. A small project that needs a README would find Markdown the best fit. Larger projects like Linux distros that produce long-form guides may find DocBook the right choice. Whatever you choose, the important thing is keeping your documentation updated and available.
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.
12 Comments