Is your documentation created "last minute" ?Back to References
Documentation is a part of the product required by the law and the directives. Country-specific and regional regulations define its obligatory parts, even up to the structure.
”When an accident happens, the company management is always primarily responsible, and what is always checked first is the documentation”, points out technical documentation specialist Jukka Toimela. He works at Etteplan’s Tampere office.
The quality requirements for the documents are high. And need for product revisions, language versions, version management and maintenance comes on top of those.
”Nevertheless, in many companies technical documentation is still considered a necessary evil that is often handled only in the last minute. In many cases, designers and supervisors produce the documents carelessly, among their other duties”, Jukka Toimela marvels.
”It is crystal clear that documentation calls for dedicated specialists, capable of handling the entity, regulations, requirements and efficient methods. High-quality documents are most efficiently produced by co-operation between professional document editors and designers”, emphasizes Jukka Toimela.
A good document serves the reader
The most important aspects relate to security. How to install, use and service the product without harming oneself or the environment. How to avoid damaging the product. Security aspects are described in three steps. What is the risk, what does it imply and how can it be avoided”, lists Jukka Toimela.
”The documents need to be concise, clear and as much illustrated as possible, presenting the items in the correct order and showing a clear structure. They need to serve mechanics, users, maintenance personnel and all other user groups”, Jukka Toimela names. The picture on the right shows the HyperSTE tool that checks the content for clarity.
The editor must keep clearly in mind the users of the document. It needs to respond briskly to the probable questions of the user. Instead, the in-depth questions of an engineering colleague will not be answered, unless he is an anticipated reader.
”You can’t over-emphasize the role of pictures. Successful artwork is an essential part of a high-quality document”, highlights Jukka Toimela.
”Good to know” instructions inform the reader about good methods and practices. Remember to add these. Remarks and advice on how to get the device work correctly. A user manual describes how functions and features are exploited to the fullest and so on.
The structure of a good document, i.e. its Table of Contents, is in order.
”The basic principle of a structured document is simple: it is divided into modules, whose versions and translations into other languages are managed separately”, Jukka Toimela summarizes. The picture on the left shows the HyperDoc content management system.
A module responds to a single question or describes a single task. For instance, how the engine is started. A change applied to a task affects only one module. The change and correct information appears automatically in every publication using that module. The change in the task affects only one module. A typical module is 1-1.5 pages long.
Maintenance becomes significantly easier. A change applied to a task affects only one module. The change and correct information is automatically cascaded to all, even dozens of publications where the module is used.
A structured documenting system creates the layouts of different language versions automatically. A picture and related text appear in the same page, even though the text length within language versions varies. This feature saves a lot of craftsmanship.
Savings in translation costs
”In some companies, designers make their contributions to the documents with varying English skills and terminology. Translators face an almost impossible task. Language versions result expensive and not that much of a quality”, tells Jukka Toimela.
A solution for also this problem is documentation professionals with efficient methods and tools.
A module appearing in several publications of a structured system needs to be translated only once. Managing the product revision translations gets more effective, too.
English and Chinese translations are created for the version A of the product. Upon releasing the product revisions B and C, the English language module is updated accordingly. Chinese language version is, however not needed to be updated if only the product version A is delivered to China.
The materials are stored in a translate memory. The translate memory tells which sentences have already been translated, which ones have only minor changes to be made and which ones need to be fully translated. A certain sentence needs to be translated only once.
Doors open for the future
”We are effectively utilizing the potential of digitalisation. When information is published on a smart device interface, instructions need not be sought from paper manuals. The systems are also ready for publishing, for example, in augmented reality environments”, praises Jukka Toimela.