The three levels of technical documentation
Compare the three maturity levels of technical documentation - from informal notes to modular structured content - and see what sets each stage apart.
Definition
Section titled “Definition”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.
The three maturity levels of technical documentation.
The three levels compared
Section titled “The three levels compared”Three components set the levels apart: the documentation process, the team, and the formats.
| Level 1: the wasteland | Level 2: the English garden | Level 3: the French garden | |
|---|---|---|---|
| Process | None | Reliable | Reliable |
| Team | Whoever happens to be available | Dedicated | Dedicated |
| Formats | Unsuitable, or suitable but used inconsistently | Suitable but unstructured, used consistently | Structured, used consistently |
| Format examples | Word processing | FrameMaker type | DocBookA semantic XML markup language for technical documentation, organized in books, chapters, and sections rather than typed topics. It predates DITA XML and is the usual point of comparison when choosing a structured format.View in glossary →, DITA XMLA structured, modular XML authoring architecture built around the concept/task/reference typology and content reuse via conrefs and ditamaps.View in glossary → |
| Content model | - | Topic-based documentation | Structured DITA XML |
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.
What each step up brings
Section titled “What each step up brings”- From the wasteland to the English garden
- A reliable process, a dedicated team, and suitable formats used consistently. The English garden - cultivated but informal - is already a fine place to be: it guarantees quality information for the user.
- From the English garden to the French garden
- Structured formats. 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.
Where does your documentation stand?
Section titled “Where does your documentation stand?”Ask the three questions the levels are built on:
- Process. Is there a reliable documentation process?
- Team. Is documentation produced by a dedicated team, or by whoever happens to be available?
- Formats. Are your formats suitable and used consistently? Are they structured?
If the answer to any of the first two questions is no, or your formats are unsuitable or used inconsistently, you are in the wasteland. With a process, a team, and suitable but unstructured formats, you are in the English garden. Structured formats on top of both make it the French garden.