document engineering

Technical documentation

Documentation technique - DITA DOCBOOK S1000D

As a logical result of the application of document engineering and technical documentation. It puts the concepts of the latter into practice.

Technical documentation consists of a pool of documents that can be clearly and unambiguously understood.

Professional tools are based on a standardized markup language. This can range from XHTML used in a strict manner to large established standards such as DocBook or DITA (S1000D for aeronautics).

The advantage of these tools and formats is that they are powerful and reusable.

However, they have the disadvantage of being very abstruse at first glance. It is therefore important to entrust these tools to trained and specialized collaborators, otherwise the final result may be counterproductive.

Usually, technical documentation is classified into three levels:

Day to day :

  • No use of a document workflow.
  • Authoring of document content by a non-dedicated team – staff assigned to other tasks.
  • Use of non specific tools and formats or inappropriate use of specific formats.

Unstructured but professional

  • Management through a tailored documentation workflow.
  • Creation of documentary content by a dedicated team – collaborators/contractors attached primarily to the creation of documentation.
  • Use of tools such as word processors that do not distinctly separate content from formatting.

Structured and professional

  • Management through a tailored documentation workflow.
  • Creation of documentary content by a dedicated team – collaborators / subcontractors attached primarily to the creation of documentation.
  • Use of specialized tools and clear separation between content and formatting.
Documentation technique - les outils

And obviously intermediate forms where the format is partially separated from the content. FrameMaker (unstructured) is an example of a relatively accessible professional tool that allows for example the creation of a book in a professional way without providing flexibility and reusability.

Practicality

.
Unstructured professional management fits perfectly in many cases. It guarantees quality content, good traceability and a relative insurance that the documents will last.

A structured professional management ensures, in addition to the advantages stated above, a significant reduction of maintenance, translation and publication costs. But as we mentioned before, the employees must be trained, otherwise the expected benefits will not be achieved.
To avoid such situations, it is possible to work with tools that separate the formats (e.g. XML) from the presentation in an editor. This makes writing easier and training is drastically reduced.

In conclusion, only the combination of dedicated processes, an adapted team and a format that separates the content from the presentation guarantee an optimal result.

This is the case for all professions, and technical documentation is no exception.