The three levels of technical documentation
Picture technical documentation as a garden. Seen that way, it falls into three stages, depending on how it is tended.
The metaphor turns on a point of garden design: an English garden looks natural but is still deliberately planned, while a French garden imposes a visible, geometric order - much like the difference between unstructured and structured documentation.
Level 1: the wasteland
Section titled “Level 1: the wasteland”- No documentation process.
- Documentation produced by whoever happens to be available - no dedicated team.
- Unsuitable formats, or suitable formats used inconsistently.
Level 2: the English garden - topic-based documentation
Section titled “Level 2: the English garden - topic-based documentation”- A reliable documentation process.
- A dedicated team.
- Suitable but unstructured formats, used consistently.
Level 3: the French garden - structured DITA XML
Section titled “Level 3: the French garden - structured DITA XML”- A reliable documentation process.
- A dedicated team.
- Structured formats, used consistently.
A word on the formats themselves. Word-processing formats are unsuitable for technical writing: they don’t separate content from layout cleanly enough. FrameMaker-type formats are suitable - they separate layout from content, more or less - but they are not semantic. The structured formats are the semantic ones, such as DocBook and DITA XML.
The English garden - cultivated but informal - is already a fine place to be: it guarantees quality information for the user. The French garden - formal, deliberate, every element in its place - goes further, giving a company tighter control over its content and lower production costs. That second step is the move from mere technical writing to true technical communication.
No single component carries the result on its own. Hand DITA XML tooling to people whose real job isn’t technical communication, or skip a proper documentation life-cycle process, and the outcome will disappoint no matter how good the format. Only the three together - process, dedicated team, and suitable format - deliver the result you’re after.