Close

Is your documentation created "last minute" ?

Published: 30.01.2018 - 13:00:00
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.

Controlled versions

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.

More information

Jukka Toimela
Technical Documentation expert and enthusiast
Etteplan, Tampere

Related content

Manuals 2.0 for Boon Edam

Every day Boon Edam, a leading manufacturer of revolving doors and security barriers, delivers beautiful products that are crafted to perfection. An excellent product deserves a manual equally as great. One that does not require any explanation, and makes life easier for the mechanic and the end user. For Boon Edam this has not always been the case. Bert Dammers, Manager Information & Document Management at Boon Edam, and his team give us a look into what it took to be able take great pride in the company's manuals.

ABB Motors and Generators

ABB Finland’s Motors and Generators unit sought new efficiencies for its product catalogue creation process. To achieve this, the unit adopted Etteplan’s HyperDoc. As a result, the unit is now able to use its resources more efficiently and apply minor global changes to its catalogues with very little effort.

John Deere

John Deere Forestry began its operations in Finland in 2000 and currently has some 700 employees in Tampere and Joensuu. The company is part of the global Deere & Company Group, the world’s leading manufacturer of agricultural, construction and forestry machinery. The company’s headquarters for wheeled cut-to-length (WCTL) machinery are located in Tampere, and the Joensuu plant produces large volumes of WCTL forest machines annually.

KONE

Modernizing old elevators and installing new ones in existing buildings is a major business for KONE. Thanks to KONE’s technology, the elevators can easily be installed even in limited spaces while respecting the building’s architecture.

Contact us
Jukka Toimela
Jukka Toimela
Sales Manager