Expert Interview: How to Write Good Technical Text

Leena Haapoja
Senior Technical Writer Etteplan Design Center

Today we are interviewing Leena Haapoja, a Senior Technical Writer from Etteplan Design Center.

She has been working in the field for 20 years, writing system documentation and user guides for hardware and software products. She is now sharing with us her best practices and possible pitfalls to avoid when dealing with technical text.

Haapoja fell into the career soon after her translation studies at university. She wanted to make use of both her language and writing skills and found the perfect combination in technical writing – a broad field that encompasses communication between design engineers, end users and various stakeholders.


In her work, Haapoja collects information about a product and expresses important details about the design for future communication. She works with multiple formats of documentation and is used to finding information from figures and mechanical drawings. The work is mainly independent, but there are often situations where information about the component has never been written down, or even planned, in which case close collaboration with subject matter experts is a must.

“One of the most important things,” Haapoja says, ”is to be open-minded, and not to be afraid to ask those famous “stupid questions”.

Technical writers are not engineers by background, and they do not need to be. The beauty of the profession is that they stay separate from the design process, and therefore, can act as a link between the reader and the engineers. “We normally have the ability to express complicated technical issues in a user-friendly way,” explains Haapoja.

In today’s world where people are constantly more interconnected; products are being shipped between continents, teams work across borders and across cultural boundaries, Haapoja’s focus is very valid and ever more important.

“The most important thing is to get to know your audience! Technical communicators’ key mission is to give the correct information in a way that is as user-friendly and as concise as possible. How complicated or simple the language is, always depends on the audience. One must keep in mind that most of the readers are not language professionals but they still have to be able to understand the message and act accordingly.”

“In the field I am working in now,” she explains, “the users of the documentation are service engineers who use work instructions related to certain maintenance tasks. They are often very experienced technicians, but their English knowledge is not perfect. In this kind of environments, it is essential to use consistent terminology and simplified language so that the message gets through.”




Top tips for writing good technical text:

1. Apply simplified technical language as much as you can (see below)
2. Use common words and expressions
3. Use short sentences
4. Give one idea per sentence




“Also, avoid giving too much background information about the technical features,“ she adds, “the user does not need that or if they do, they should be directed to further information that is presented somewhere else.”

An example from the Simplified Technical English, ASD-STE100-standard below, shows how using these best practices can help you modify an ambiguous sentence into a clear set of instructions.



Original sentence:


The side stay assembly has two folding toggles hinged together and attached with hinges between the main gear strut and the side stay bracket.




Simplified (STE):


The side stay assembly has two folding toggles. The folding toggles are attached together with hinges. These toggles are also attached with hinges between the main gear strut and the side stay bracket.


Illustrations are also an important tool in technical communication

Illustrations are heavily used in all forms of technical writing, whether it is technical specifications or user guides. Illustrations can describe certain details of a design in a way that text can’t, and they often make the material easier to read. “Sometimes the entire text can be replaced by just illustrations,” explains Haapoja, ”but the more complicated the subject is, a combination of both is needed ”.

Choosing the right technology for the job

The raw information Haapoja normally works with, comes to her in various formats, but is often in Word or PDF files stored in content management systems. The most efficient way to create technical documentation is applying modular documentation and Darwin Information Typing Architecture (DITA) with a content management system. In DITA the documentation is created in modules that are being written with an XML editor (such as Arbortext, XMetal, Oxygen), or Adobe FrameMaker. Using modules enables reuse of information without it being stored as copies in multiple files. In her current working environment, Haapoja is simply using Microsoft Word, but she emphasises, that being only a text processing software, it is not the ideal tool for creating technical documentation.

“It is often so, that there are many common sections in company’s written material, and when a text editor is used, the reuse of this material is impossible.”

Technical writing is a skill of its own, and enables good communication with customers, colleagues and various stakeholders. Without this level of understanding many projects would run long, work would need to be redone and the customer experience would be affected. Specialist organisations, such as the Etteplan Desing Center, harvest and improve these skills. To find out more about the field and to start improving your writing, visit Technical Communication in Europe and ASD-STE-100.



For further information see:

Tekom Europe

DITA

Suomen Teknisen Viestinnän Yhdistys (Finland only)