4 markup languages for open source project documentation

Markup lowdown: 4 markup languages every team should know

Image credits : 

Photo by Unsplash; modified by Rikki Endsley. CC BY-SA 4.0

x

Get the newsletter

Join the 85,000 open source advocates who receive our giveaway alerts and article roundups.

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.

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.

About the author

Ben Cotton - Ben Cotton is a meteorologist by training and a high-performance computing engineer by trade. Ben works as a product marketing manger at Microsoft Azure focused on high performance computing. He is a Fedora user and contributor, 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...