The three levels of technical documentation
If we compare technical documentation to a garden, we can classify it according to the following levels:
Wasteland
Section titled “Wasteland”- No documentation process used.
- Documentation created by non-dedicated teams.
- Use of unsuitable formats or inconsistent use of suitable formats.
English garden
Section titled “English garden”- Use of reliable documentation processes.
- Documentation created by dedicated teams.
- Consistent use of adapted but unstructured formats.
French garden
Section titled “French garden”- Use of reliable documentation processes.
- Documentation created by dedicated teams.
- Consistent use of structured formats.
Formats that are not suitable for technical writing include word-processing formats, which do not sufficiently separate layout from content.
Suitable formats are FrameMaker-type formats, which (relatively) separate layout from content, but are not semantic.
Structured formats are semantic formats such as DocBook or DITA XML.
The English Garden stage is already very satisfactory, and guarantees that quality information is provided to the user. The French Garden stage also enables companies to better control their content and reduce production costs.
The presence of any one of the three components (process, dedicated team, and adapted format) alone cannot guarantee a satisfactory result. For instance, if you entrust tools for generating content in DITA XML format to employees whose core business is not technical communication, or if you do not implement a technical documentation lifecycle management process, you’ll achieve disappointing results. Only the combination of these three elements will deliver optimal results.