Communications from DMN

Over the last few weeks, I’ve been thinking about and using markup languages quite extensively. Not the markup languages that you normally associate with documentation — like HTML, XML, or even LaTeX. I’ve actually been doing some work with lightweight markup languages, specifically one called Markdown. My focus has been using Markdown to write articles and blog posts (including this one); you can read more about my adventures with Markdown here.

Why go lightweight?

One aspect of lightweight markup languages that I find useful is their simplicity. For the most part, at least. You do all of your writing in a text editor. The markup that these languages is what makes them lightweight. The syntax that they use is similar to wiki syntax — keyboard characters are used to define formatting. You can find some examples here.

On top of that, the processors for various lightweight markup languages can convert documents to higher-level forms of markup like DocBook XML, HTML, and LaTeX. You can transform DocBook and LaTeX output to Postscript, PDF, certain online help formats, or even UNIX man pages. I haven’t found a lightweight markup language that supports DITA output, though.

While languages like Markdown are fine for the simple uses I’ve put them to, can they be used for documentation? It really depends on the markup language, what documentation you’re developing, and how you want to present your documents.

Looking at AsciiDoc

Of all the lightweight markup languages that I’ve worked with — and there are a number that I haven’t touched — the one that’s best suited to documentation tasks is AsciiDoc. Two others, reStructuredText and Txt2Tags, also look suitable. But I haven’t worked with them enough to form any kind of opinion of their capabilities.

AsciiDoc is two things. First, it’s a human-readable formatting scheme. AsciiDoc markup is very similar to that used with a wiki — keyboard characters are used to specify and a Python script and a set of configuration files for transforming a document that is marked up to a number of different output formats. These formats include HTML and XHTML, UNIX man pages, DocBook, and LaTeX.

While AsciiDoc is really meant for shorter documents, some people — including its author — have written and output longer documents, too. The output doesn’t look too bad (here’s the AsciiDoc manual, which was first converted to DocBook XML and then to PDF), although with just about any lightweight markup language you may run into problems with widows and orphans in generated PDF files. You can, of course, control the look an feel of the output using Cascading Style Sheets, a DocBook customization layer, or your favourite LaTeX document class.

Output, output

As mentioned earlier, you can generate documents formatted with more complex markups from an AsciiDoc source. From there, you can output your documents into other formats. Out of the box, you’ll be stuck with the standard look and feel of the output formats — unless, of course, you have custom DocBook, LaTeX, or HTML stylesheets. You can also use such intermediate converters as docbook2odf to convert output files to another format over which you have a little more control. But that could be a lot more trouble than it’s worth.

You’ll notice, though, that AsciiDoc (and most other lightweight markup languages) don’t support direct output to RTF- or HTML-based online help formats. Your best bet is to use DocBook, which supports output to HTML Help (uncompiled), Javahelp, and WebHelp formats. Or, you can generate chunked HTML and import it into a tool like HTML Help Workshop or RoboHelp. Again, that could be a little more work than it’s worth.

Single sourcing

This is the big one. And, unfortunately, most lightweight markup languages fall short in this area. And, again, to do any meaningful single sourcing you’ll have to convert the marked up files to DocBook and add the markup for profiling (DocBook’s term for conditional text).

AsciiDoc enables you to combine individual sections into a single document. You don’t get the topic-based granularity of DITA, but you do get a bit more control over what goes into a document.

Conclusion

If your documentation needs are simple, and you have a low or non-existent budget, then a lightweight markup language might be worth investigating. If you’re doing any sort of single sourcing or component-based writing, then I’d consider something else. The better lightweight markup languages are good for what I call monolithic single sourcing: creating multiple outputs of a large document, where you split the document out into manuals for different levels of user experience and different operating systems, as well as into multiple formats.

That said, I’ll continue to using Markdown to write articles and blog posts — especially when I’m offline and want to knock off a few quick posts. But for writing documentation, I’ll stick with the industry-standard tools. There’s really no way a lightweight markup language can compete.

What’s your take on this? Feel free to leave a comment.