Back

Is your documentation created "last minute" ?

30.01.2018 industrial , medical , industrial applications , product certification

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.

Picture 1. HyperSTE software checks content for clarity.

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 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.

Picture 2. HyperDoc content management system.

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.

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.

Picture 3. augmented reality example.

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


Latest articles

  • Powering up testing – getting a grip on software projects 05.05.2017 testing , agile , continuous integration

    Well designed and correctly carried out testing and testing automation help to keep projects on schedule. The maintainability and control of the system is improved, and even the product's life cycle can be extended. The engineers at Etteplan have had good experiences with the Jenkins and Robot Framework systems.

  • Renovating testing environment with Procket Rapid 13.06.2017 testing , test systems , production testing , agile , continuous integration

    Embedded system is a combination of both hardware and software, the testing and development of which calls also for other things than just software and the device itself.

  • TOSIHack, Turku 3.2.2018 05.02.2018 testing , industrial internet , software , security

    Tosihack was a security testing event organized by Etteplan, Tosibox and TurkuSec organization in Turku at Saturday 3.2.2018. A total of 17 hackers joined the event in four teams.

  • Ekahau Sidekick – measurement powerhouse for Wi-Fi professionals 11.01.2018 wireless , laboratory , electronics , product certification

    World’s first all-in-one Wi-Fi network diagnostics and measurement device facilitates Wi-Fi network testing, validation, documentation and troubleshooting. Ekahau Sidekick covers both 2,4 and 5 gigahertz and standards 802.11 a/b/g/n/ac up to -95dBm sensitivity.

  • Less prototyping rounds and EMC challenges with simulation 29.12.2017 wireless , production testing , laboratory , electronics

    Simulation speeds up design and helps improve the end product quality. Simulation suits nicely for example for antenna design, for analysing EMC, RF interoperability, shielding effectiveness and radiating fields. It can also be used to review the current layout, design and mechanics.

  • Is your documentation created "last minute" ? 30.01.2018 industrial , medical , industrial applications , product certification

    The technical documentation is still considered a necessary evil that is often handled only in the last minute. Modern practices in creating the documentation ensure easy-to-maintain, high-quality documents that are an essential part of the product.

  • Designer! Do not forget security in your IoT system 25.01.2018 industrial internet , industrial , security

    A specialist warns: a carelessly constructed Internet of Things system is a serious security risk. White-hat hackers hunt for vulnerabilities in a respected Finnish IoT security product at Tosihack event 3 February 3, 2018.

  • Industrial internet increases requirements for antennas 28.12.2017 industrial internet , wireless , laboratory , electronics

    Wireless devices are becoming more common due to industrial internet. The antenna performance is often characterized by three parameters: efficiency, gain and selectivity...

  • Product certification – case Asqella 17.12.2015 testing , laboratory , product certification

    Nowadays more and more products contain electronics and maybe some kind of wireless technology. People do not always realize that all electronic device must be certified, in other words checked, tested, and approved, before the sales of the product can start.

  • NB-IoT Breakfast 27.9.2017 27.09.2017 industrial internet , wireless , telecom , electronics

    Great NB-IoT session today, with speakers from Ericsson, DNA, u-blox and F-Secure. Some pictures and the presentation materials available here...