Markup lowdown: 4 markup languages every team should know

No readers like this yet.
open source button on keyboard

Opensource.com

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.

User profile image.
Ben Cotton is a meteorologist by training, but weather makes a great hobby. Ben works as the Fedora Program Manager at Red Hat. He is the author of Program Management for Open Source Projects. Find him on Twitter (@FunnelFiasco) or at FunnelFiasco.com.

12 Comments

best among all is asciidoctor (www.asciidoctor.org).
It implements "asciidoc" markup language and also supports standard markdown. It has very clean syntax, it is not sensitive to whitespace like restructured text, but it is still as powerful as restrucutredtext.
Use asciidoctor.

zax,
I've been trying to find someone to write an article for us on asciidoctor. I heard about it earlier this year and would love to include it in our documentation column. If you know anyone who might want to write about it for us, send them our way (open@opensource.com)

In reply to by zax (not verified)

I'm using Markdown (well, actually, GitHub flavoured Markdown) for everything I do that requires me to type more than 15 words: writing emails, writing docs, writing articles, submitting issues, keeping a todo list...

No love for groff/mom? Also, what is it about LaTeX you find aesthetically lacking?

"Also, what is it about LaTeX you find aesthetically lacking?"

I was about to ask the same question. Many books, journals etc. have been produced used LaTeX and I have never seen this criticism before.

Personally, I'm a fan of lyx, a GUI front-end to LaTeX. It's what I used to produce a text book for my students.

In reply to by Donnie (not verified)

It is surprising that in this day and age of the internet, that HTML is not on the list.

I use ckeditor with a few mods to file into a DB as part of a general web/document control system.
HTML wysiwyg editing and immediately ready for web. Its got latex addons should you need formulae.
Fits any screen, immediately accessible and practically zero training required.

Asciidoctor is great. It is coded in Ruby (the predecessor asciidoc is in python), and there is a version that compiles to JavaScript so it renders great in the browser.

I really view latex and docbook as intermediate formats. Asciidoctor converts to docbook, and restructured text converts to latex. Write in something else, and then tweak in docbook or latex. Years ago I did go through my phase of writing directly in latex and docbook.

For me, restructured text and sphinx FTW. I get great text markup and I am more comfortable with python as the underlying code. My documents are also more complicated than what markdown can handle.

I'll have to take a look at asciidoc for my own personal interest.

I must say that I am surprised to see markdown's limitations cited without mentioning multimarkdown as an alternative. It seems to be the variant that (a) has the most interest and (b) goes a long way toward eliminating markdown's limitations while still retaining its very simple markup style.

One of markdown's (and, by extension, multimarkdown's) strengths is the ability to just write without worrying about how the final output will look. Anyone who has written a document of any length in a markup language like SGML, HTML, or LaTex knows the pain that I'm referring to. Every time that a writer has to stop to think about formatting, it interrupts the creative flow. Getting back to the topic at hand every time this happens takes time. The more frequent the interruption, the more complex the formatting language itself is, the more the overall writing process slows down.

This is why markdown and reStructured Text were invented, after all. Writers need something simple that gets out of the way. Finding something that does that job well while not sacrificing too much in the way of capability will always be a challenge. I think that multimarkdown does so at least as well as anything else that has been discussed here.

3/4

I've not used only LaTeX.

We use Gitbook as markdown postprocessor. It offers some infrastructure to get an index & chapters.
We also have some scripts that gather documentation from the source code, and produce swagger.io interactive documentation, plus executed examples.

interesting Article ,thanks for sharing !!

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