Why I love these markup languages

3 readers like this.
Typewriter keys

Original photo by Bob Doran via Flickr. Modified by Rikki Endsley. CC BY-SA 2.0.

Around this time last year, I wrote a brief introduction to various markup languages for this column. The topic of language selection has come up several times recently, so I thought it might be time to revisit the subject with my biases more overt. I'm here to explain why I prefer the languages I do, not to prescribe anything for you. After all, I'm no doc-tor.

A colleague asked my opinion of a post comparing reStructuredText and Markdown for technical documentation. My company's docs are written in reStucturedText rendered with Sphinx, but I've made noise from time to time about moving to something like DocBook XML. For me, reStructuredText fits in the anti-Goldilocks zone where it's not super simple like Markdown, but not as rich as DocBook XML. Where it shines is using Sphinx to auto-generate module documentation for Python.

Recently, the lead maintainer of the Copyleft Guide announced his intention to switch from LaTeX to either CommonMark or AsciiDoc. Having never used AsciiDoc, I was a little surprised at how strongly I argued for it, but as I had follow up conversations, I realized it's an excellent fit for book-like documentation.

"Separate the content from the presentation," they say. Languages like DocBook and AsciiDoc allow the author to say, for example: "This is a GUI button." It may end up rendered bold, but you don't just add <em> and call it a day. The content is separated from the presentation; for example, rendering tools like Asciidoctor use cascading style sheets (CSS) to control the presentation.

My favorite thing to do in book-ish documentation is to include callouts. Warnings, tips, etc. are important features for your reader. In most cases, the reader is going to end up skimming parts of the book, either because they're looking for a specific part or because your prose is too boring and they've lost interest. Calling out the particularly important parts helps make sure the reader gets the information you really, really want them to know. Plus, they add nice breaks to walls of text. In fairness, reSTructuredText has some support for these, but I've never been able to make them as pretty or as obvious-in-source as I'd like.

Now what haven't I heaped praise on yet? Markdown. Poor Markdown. Don't get me wrong, I love Markdown. This very article was submitted to the editors in Markdown. I took my lecture notes in school in Markdown. It's so easy to write as you go and to read in source form. For short, standalone documents, Markdown is the best.

But the ease of writing Markdown is at odds with the ultimate (lack of) power of Markdown. Unless you embed a lot of HTML (and then you might as well not use Markdown), you're not going to get a lot of the semantic richness that becomes more important in long-form material. It's tempting to pick Markdown for everything because it makes the barrier to contribution so low, but when choosing to make life easier for the developers or the users (writers and readers, in this case), successful projects tend to favor the user.

So there you have it. Documentation languages are not one-size-fits-all, so picking the right fit for the document being written is crucial.

Tell me why you love your language of choice in the comments.

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

I don't like Markdown because of it ambiguity. Any markup that is hard to parse is hard to understand.

I'm curious what you think is ambiguous about Markdown syntax compared to other markup languages. Is it just that `**` is less expressive than `<b>`?

In reply to by Shawn H Corey (not verified)

I'll have to check out the different suggestions here. I switched to Markdown about a year ago for all note taking at work and otherwise. I then use pandoc to get it into PDFs at the end of the project or year. For anything longer I use LaTeX. When I moved all my notes at work, including pictures, from OneNote to Markdown I went from 800+ MB to less than 800 KB.

When I was in grad school, all of my notes were in Markdown. At the end of each unit, I'd render the notes to HTML, print that (yes, as in "dead tree") and use that to study. Apart from the data for my thesis, the entirely of my grad school life fit into a few tens of megabytes.

In reply to by jimmysjolund

My sentiments exactly: "Documentation languages are not one-size-fits-all, so picking the right fit for the document being written is crucial." Markup languages are like any tool. You can shoehorn a language into a task it's not quite suited to, but that's a lot like trying to hammer a nail with a screwdriver. You can probably do that, but not without a lot of effort and swearing. The results can be ugly, too.

Having cut my document-editing teeth on Word Perfect's "Reveal Codes" functionality, I find that just working in straight semantic HTML tends to work best for me. Wrote all my college papers in HTML using a text editor, and still do all documentation in raw HTML. Benefits include backwards compatibility (I can still view/print my papers from the late 90s with no issues), no need for any tools to convert *to* HTML, fairly easy semantics, and a broad range of built-in mark-up for lists, side-bars, captions, tables, and the like. Every other mark-up language (well, except perhaps DocBook) has me running to the docs to check syntax any time I want to do something more than the basics.

The only tricky part I've encountered has been doing foot-notes/end-notes, but I've hacked together a little JavaScript that converts in-line footnote span elements to end-notes (foot-notes are more complex since they would require a print style-sheet).

Is this for your own use, or do you do this for collaborative projects, too? If you collaborate that way, how does that work out for you?

In reply to by Tim Chase (not verified)

I feel like markdown is great, until you start wanting to override layout. I think there's an unspoken agreement when using markdown: you promise not to think about final formatting and layout. If you betray that agreement, then you suffer the consequences of having used markdown.

This is more or less how I feel about most pre-fab solutions, though; for ease, you sacrifice flexibility. Not a bad thing, just something to be aware of before adopting.

I think every idea that I have that gets written down and involves more than three lines of text inevitably passes through a period in which it is written in Markdown, or at least, I give it a # header and some * bullets. I also tend to add *various* forms of _emphasis_ to things I write, whether or not it ever gets rendered into anything. If it gets long enough that I think it's becoming something that's more than a note to self or an email, and becomes something that I might publish, I almost always end up converting to HTML before it's even halfway done. Different people go through their creative process (which may or may not be different than procrastination) in different ways; for things I publish, my way always involves playing with the rendered output way before the text is fully written.

I'm with you. Even my informal notes that I take just to capture what was going on so that I can do actual writeups later tend to be, if not valid Markdown, darn close. I've noticed that even my handwritten notes have a distinctly Markdown flair these days.

In reply to by Jason B

Markdown: The little markup language that could. ;-D

I've become a big fan of one of its offshoots; multi-markdown. The additional syntax is still simple enough to just write without worrying about how it's going to look, produces output that looks pretty good on its own, and is easily tweakable via any number of tools before final output as HTML, EPUB, PDF or whatever. Perfect for writing those long documents without bogging you down learning Yet Another Markup Language.

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