Our favorite markup languages for documentation

Documentation is important for so many reasons. Readable documentation is even more so. In the world of open source software, documentation is how to use or contribute to an application. It's like the rulebook for a game. 

There are many different types of documentation:

• Tutorials

• How-to guides

• Reference guides

• Software architecture

• Product manuals

We asked some of the Opensource.com contributors about their technical documentation workflow, which markup language they preferred, and why they might use one over the other. Here's what they had to say.

AsciiDoc

For the past several years, Markdown has been my standard language. But recently I decided to give AsciiDoc a try. The syntax is not difficult and Gedit on my Linux desktop supports it. I plan to stick with it for a while.

—Alan Formy-Duval

In terms of low-syntax markup, I prefer AsciiDoc. I like it because its conversion process is consistent and predictable, with no surprise "flavor" variations to confuse things. I also love that it outputs to Docbook, which is a markup-heavy syntax that I trust for longevity and flexibility.

But the "right" choice tends to be what a project is already using. I wouldn't write in AsciiDoc if a project uses Strawberry-flavored Markdown. Well, to be fair, I might write in AsciiDoc and then convert it to Strawberry-flavored Markdown with Pandoc.

I do think there is a time and place for Markdown. I do find it more readable than AsciiDoc. Links in AsciiDoc:

http://example.com[Example website]

 Links in Markdown:

[Example.com](http://example.com)

The Markdown syntax is intuitive, delivering the information in the same way that I think most of us parse the same data when reading HTML ("Example website…oh, that's blue text, I'll roll over it to see where it goes…it goes to example.com").

In other words, when my audience is a human reader, I do often choose Markdown because its syntax is subtle but it's got enough of a syntax to make conversion possible, so it's still an OK storage format.

AsciiDoc, as minimal as it is, just looks scarier.

If my audience is a computer that's going to parse a file, I choose AsciiDoc.

—Seth Kenlon

reStructuredText

I'm a big fan of docs as code and how it brings developer tools into the content workflows. It makes it easier to have efficient reviews and collaboration, especially if engineers are contributors. 

I'm also a bit of a markup connoisseur, having written whole books in AsciiDoc for O'Reilly, a lot of Markdown for various platforms, including a thousand posts on my blog. Currently, I'm a reStructuredText convert and maintain some of the tooling in that space. 

—Lorna Mitchell

Obligatory mention of reStructuredText. That's my go-to these days as I do a lot of Python programming. It's also been Python's standard for documentation source and code comments for ages.

I like that it doesn't suffer quite so much from the proliferation of nonstandards that Markdown does. That said, I do use a lot of Sphinx features and extensions when working on more complex documentation.

—Jeremy Stanley

HTML

I rarely use markup languages if I don't have to.

I find HTML easier to use than other markup languages though.

—Rikard Grossman-Nielsen

For me, there are various ways to make documentation. It depends on where the documentation is going to be whether on a website, as part of the software package, or something downloadable.

For Scribus, the internal documentation is in HTML, since an internal browser is used to access it. On a website, you might need to use a Wiki language. For something downloadable you might create a PDF or an EPUB.

I tend to write the documentation in a plain text editor. I might use XHTML, so that I can then import these files into an EPUB maker like Sigil. And, of course, Scribus is my go-to app for making a PDF, though I would probably be importing a text file created with a text editor. Scribus has the advantage of including and precisely controlling placement of graphics.

Markdown has never caught on with me, and I've never tried AsciiDoc.

—Greg Pittman

I'm writing a lot of documentation in HTML right now, so I'll put in a plug for HTML. You can use HTML to create websites, or to create documentation. Note that the two are not really the same — when you're creating websites, most designers are concerned about presentation. But when you're writing documentation, tech writers should focus on content.

When I write documentation in HTML, I stick to the tags and elements defined by HTML, and I don't worry about how it will look. In other words, I write documentation in "unstyled" HTML. I can always add a stylesheet later. So if I need to make some part of the text stronger (such as a warning) or add emphasis to a word or phrase, I might use the <strong> and <em> tags, like this:

<p><strong>Warning: Lasers!</strong> Do <em>not</em> look into laser with remaining eye.</p>

Or to provide a short code sample within the body of a paragraph, I might write:

<p>The <code>puts</code> function prints some text to the user.</p>

To format a block of code in a document, I use <pre><code>..</code></pre> like this:

void
print_array(int *array, int size)
  {
  for (int i = 0; i < size; i++) {
  printf("array[%d] = %d\n", i, array[i]);
  }
}

The great thing about HTML is you can immediately view the results with any web browser. And any documentation you write in unstyled HTML can be made prettier later by adding a stylesheet.

—Jim Hall

Unexpected: LibreOffice

Back in the 80s and 90s when I worked in System V Unix, SunOS, and eventually Solaris, I used the mm macros with nroff, troff and finally groff. Read about MM using groff_mm (provided you have them installed.)

MM isn't really a markup language, but it feels like one. It is a very semantic set of troff and groff macros. It has most things markup language users would expect—headings, numbered lists, and so on.

My first Unix machine also had Writers' Workbench available on it, which was a boon for many in our organization who had to write technical reports but didn't particularly write in an "engaging manner". A few of its tools have made it to either BSD or Linux—style, diction, and look.

I also recall a standard generalized markup language (SGML) tool that came with, or perhaps we bought for, Solaris in the very early 90s. I used this for awhile, which may explain why I don't mind typing in my own HTML.

I've used Markdown a fair bit, but having said that, I should also be saying "which Markdown", because there are endless flavors and levels of features. I'm not a huge fan of Markdown because of that. I guess if I had a lot of Markdown to do I would probably try to gravitate toward some implementation of CommonMark because it actually has a formal definition. For example, Pandoc supports CommonMark (as well as several others).

I started using AsciiDoc, which I much prefer to Markdown as it avoids the "which version are you using" conversation and provides many useful things. What has slowed me down in the past with respect to AsciiDoc is that for some time it seemed to require installing Asciidoctor—a Ruby toolchain which I was not anxious to install. But these days there are more implementations at least in my Linux distro. Curiously, Pandoc emits AsciiDoc but does not read it.

Those of you laughing at me for not wanting a Ruby toolchain for AsciiDoc but being satisfied with a Haskell toolchain for Pandoc… I hear you.

I blush to admit that I mostly use LibreOffice these days.

—Chris Hermansen

Document now!

Documentation can be achieved through many different avenues, as the writers here have demonstrated. It's important to document how to use your code, especially in open source. This ensures that other people can use and contribute to your code properly. It's also wise to tell future users what your code is providing.