January 28, 2011

Mark-up Smackdown

In the tradition of old is new mark-up languages are making a serious comeback for professional technical documentation. In the dark ages troff and other *roff variants ruled the roost. As more writers moved into technical writing and computer graphics got more powerful WYSIWYG tools like FrameMaker and Word rose to prominence. Now the pendulum is swinging back to mark-up.
Markup languages come in two basic flavors: presentation mark-up and structural mark-up. The difference is that presentation mark-up is focused on how the text is presented and structural mark-up is focused on the structure of the content. The difference is subtle but important.
Focusing on presentation, as most current WYSIWYG editors do, tend to favor a particular presentation medium (the Web, print, slides). While the presented content appears to have a structure because it has headings and lists, etc. the underlying source has no real structure. A writer is free to use lists and headings in any way they wish. This is nice for. Writer, but makes content reuse more difficult.
Focusing on structure removes the preference for any one particular presentation medium, but it does mean that more work is required to transform the source content into a presentation medium. The underlying source has an enforced structure to which a writer must adhere. The enforced structure is limiting, but allows for easier reuse.
Among the popular current presentation mark-up languages there is a pretty consistent preference towards Web presentation. Along with HTML there are a number of wiki mark-ups in use including MediaWiki, Confluence, and MoinMoin. There is also Markdown and Textile. They all attempt to make it easier to craft good looking content on the Web. To a high degree they all succeed. I personally like Textile and Markdown because they allow the writer to mix in HTML code to fill in gaps left by the mark-up language. The draw back to all of these languages is that they do not replicate all of the functionality of HTML and their syntaxes can be fidgety. If you don't do it exactly right the resulting output is bad and there are no good tools to help you get it right.
In terms of appropriateness for large technical documentation projects, presentation languages have serious drawbacks that counteract the oft touted claim that they are way easier to use than the alternatives. Because they leave structure up to the writer and the base unit of content is a page, it is difficult to recombine content or enforce uniform structure across a documentation set. They don't generally provide tools for indexing content or thinking of organizing content beyond a single page. They also don't have easy translations into any other presentation medium than HTML.
Structured mark-up languages, such as DocBook and DITA, push concerns about presentation into backend processing stages. The mark-up itself deals with content structure. They have enforced concepts of what makes up a unit of content. DocBook uses structures like chapters and sections. DITA uses structures like procedures and reference topics. These units of information are easily combined into larger structures like books and libraries. The drawback for some writers is that there is no easy way of seeing what the content will look like when it is published. A lot of people find it easier to write when they can see a representation of the final product and feel like they need control over the design of the content on the page. Another drawback is that structural mark-up tends to be more complex than presentation mark-up. The learning curve is steeper, but there are a numbered of tools available that support content completion for DocBook and DITA.
For large scale documentation projects structured mark-up, despite its steeper learning curve, has the edge over presentation mark-up. The freely available toolchains for them provide translation into Web and print formats. They have indexing mechanisms and provide structures to support content beyond a single page or unit.
The presentation mark-up will continue to be good choices for content developed by small teams or developers. For big projects down by professional teams, structured mark-up i the future.

No comments:

Post a Comment