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.
12 Comments