Sidebar: Presentation and Structure

A key point to realise when writing technical documentation is the distinction between structure and presentation. Suppose, for example, our document includes source code snippets and we want these snippets to be preformatted in a monospaced font with keywords emphasized using a bold font style. Here, we have two structural elements (source code, keywords) and two presentational elements (monospaced font, bold style).

Structure and presentation are separate concerns and our documentation chain should enable and maintain this distinction. This means that our master document structure will need to identify source code as "source code"—and not simply as preformatted text—and any keywords within it as "keywords"; and the styling associated with the presentation of this document will make the required mapping from "source code" to "monospace, preformatted" and from "keyword" to "bold".

We can see this separation in well-written HTML where the familiar element tags (HEAD, BODY, H1, H2, P etc) describe basic document structure, and CLASS attributes make finer structural distinctions. The actual presentation of this structured content is controlled by logically (and usually physically) separate Cascading Style Sheets (CSS).

With a WYSIWYG documentation tool presentation and structure—by definition—operate in tandem, making it all too easy to use a structural hack to fix a presentational issue (for example, introducing a hard page break to improve printed layout, or scaling a font down a point size to make a table look pretty).

DocBook enforces the separation between structure and presentation strictly. This doesn't mean that we can't use a Graphical Editor to work with DocBook documents—indeed, a web search suggests several such editors exist. I chose to work with the raw DocBook format, however, partly because I could continue to use my preferred editor and partly because I wanted to get a better understanding of DocBook. The enforced separation can sometimes be frustrating, however. It took me about an hour to figure out how to disable hyphenation of the book's subtitle on my custom frontpage!

Copyright © 2006 Thomas Guest