When dealing with the topic of technical documentation for the first time, start-ups and other companies can quickly start to feel overwhelmed. This often leads to many questions, such as:
- What exactly is technical documentation?
- Why do we differentiate between internal and external documentation?
- Why do you need to take various target audiences into account?
- What legal requirements and standards are there to consider?
- What does a technical writer actually do?
- What tools do you need?
- And how can you get your technical documentation translated?
In our latest blog, we’ll provide easily understandable answers to these questions and more.
What is technical documentation?
Technical documentation (TD, also known as “product documentation”) comprises all types of documents relating to technical devices and software products. Whether online or on paper, they describe how to safely use, maintain, and/or repair such equipment.
Technical documentation is always designed for a particular purpose. In basic terms, it’s meant to enable the respective target audience – be it users, technicians, or sales engineers – to do what they need to do. It also gives manufacturers a means of protecting themselves from liability claims and fulfilling all their legal obligations.
As a general rule, we distinguish between internal and external technical documentation:
- Internal technical documentation provides an archive of all product-relevant documents. Such documents include specification sheets, test reports, risk assessments, and blueprints.
- External technical documentation, on the other hand, tells operators and users how to do things like assemble, install, use, and maintain a given product.
Who is the technical documentation for?
This is the most important question manufacturers have to answer before writing their TD: Who is our target audience? Instead of compiling a 400-page tome that addresses absolutely everyone’s needs, it’s best to create a separate document for each group.
Before you get started, think about what actions are required throughout the lifecycle of the product and who will be responsible for them. Put together a brief overview of all this information. Here’s what this might look like based on the example of a CNC lathe machine:
- Planning: people affiliated with the manufacturer
- Transport: shipping company
- Installation: people affiliated with the manufacturer
- Programming: CNC cutting specialist, programmer
- Use: CNC cutting specialist
- Maintenance: CNC cutting specialist
- Repairs: CNC cutting specialist, service technician
- Disassembly…
In this setting (which Dietrich Juhl describes in the book Technische Dokumentation*1), the CNC cutting specialist doesn’t need to know how the machine is transported or installed. What is relevant, however, are the instructions on programming, use, and maintenance.
According to Juhl, there should thus be eight different manuals for the CNC machine’s various target groups:
- Planning documentation
- Transport instructions
- Installation and commissioning instructions
- Operating instructions
- Programming manual
- Three sets of service documentation (mechanical, hydraulic, electrical)
What norms and legal requirements do you need to observe?
The people in charge of writing laws are known to be rather particular about safety. Products therefore need to be designed accordingly and present no danger to people’s well-being. In cases where risks can’t be ruled out entirely, manufacturers are required to provide relevant warnings and notices.
This is why technical documentation is subject to a wide range of norms and legal requirements, a selection of which follows:
- DIN EN 82079-1 is a norm for the creation of usage instructions. Among other things, it covers communication quality, risk mitigation, and the form and content of user manuals. It also includes free checklists that help ensure corresponding compliance. This norm should be part of any technical writer’s basic toolkit.
- EU Directive 2006/42/EC (the “Machinery Directive”) requires manufacturers to provide operating instructions in their own language (and others, if applicable) that take users’ level of knowledge and comprehension ability into account.
- The VDI 4500 standard covers various aspects of technical documentation, from terminology, organisation, and administration to the planning, design, and creation of actual documents.
- The DIN EN ISO 7010 norm presents a uniform standard for safety signs that eschews text in favour of language-independent, universally understandable signage.
- ANSI Z535 is the US norm for safety information. While it isn’t relevant for products brought to market in Europe, it is of interest to manufacturers that export machines and other devices to the United States.
- Other countries may have other regulations, such as Germany’s legislation on product safety (ProdSG), which represents the country’s implementation of EU Directive 2001/95/EC.
In addition, further regulations apply to different product groups and regions, such as the German legislation on medical products (MPG) or EU Directive 2006/95/EC (regarding low-voltage electrical equipment).
What role do technical writers play?
You might think that creating technical documentation is another task handled by engineers themselves, but it’s actually the job of technical writers. These specialists have the ability to explain complex functions and situations in ways that are easy for the respective target group to understand. They often have a direct line to the manufacturer’s development team, as well.
That said, technical documentation is obviously not the same as ad copy or other marketing materials: writing product descriptions, glossy brochures, and flyers that drive sales requires additional skills.
Technical writers who are also well versed in creating copy can handle both areas. Those who aren’t, can work with copywriters on such projects:
- The technical writer ensures that all the technical facts provided are correct.
- The copywriter comes up with attractive texts that encourage readers to make a purchase.
To learn more about the benefits of having technical writers and copywriters collaborate, check out the article How Technical Writers Fit into the Marketing Mix.
What software and tools do you need for your technical documentation?
Managing all your technical documentation can present another challenge. Manufacturers need to document in detail every functional change in their products and ensure that all their external documentation is updated accordingly. This is why Lexsys advises against managing technical documentation in Microsoft Word or other word-processing programs.
How suitable are component content management systems for technical documentation?
In recent years, content management systems (CMS) have gained popularity as a means of simplifying the creation, maintenance, and publication of TD. Even more interesting for product manufacturers, however, are component content management systems (CCMS), which are capable of storing not just documents, but individual pieces of information, as well.
These “components” can include diagrams, charts, product descriptions, or processes. They can also be as small as a single word or as extensive as an entire document.
At the heart of such systems are various document formats – DITA, for example, an XML-based architecture for creating, distributing, and reusing technical information.
How can you translate technical documentation?
Companies that want to sell their products abroad need to have their technical documentation adapted for each target country. According to the German technical communication society tekom (link in German), nearly half of all technical documents are translated into more than 10 languages.
These days, there are very few manufacturers left that have their own translators and localisation teams, which is why many of them assign such work to external translation agencies. The best agencies offer manufacturers an array of advantages because they:
- Handle all aspects of project management
- Work with a pool of highly qualified technical translators
- Offer excellent quality assurance based on ISO certification
- Possess industry-specific expertise
A professional translation agency can advise manufacturers on all matters related to the translation of technical documentation, including the pros and cons of machine translation and related post-editing – that is, having human experts review machine-translated texts.
Since the translation market is unregulated and somewhat cluttered, manufacturers should take a close look at several different providers before choosing the one they want to entrust with their technical documentation.
Here are some examples of criteria you should focus on:
- ISO 9001 certification (quality management)
- Positive customer feedback
- Transparent processes and prices
- Professional translators who work in their native language
Where can you find useful resources on this subject?
If you want to find out more about technical documentation, further helpful information is available here:
- VDI standards: Access publications on the various standards issued by the Association of German Engineers (VDI).
- tekom: The website of the world’s largest professional association for technical information offers information (in German) on specialist conventions, industry events, further training opportunities, and much more.
- 1Technische Dokumentation: Praktische Anleitungen und Beispiele by Dietrich Juhl, Springer Vieweg, 2015. Written primarily for technical writers, this guide provides many useful tips on creating various types of instructions.
Lexsys: the partner you can rely on for flawless technical documentation
The world of technical documentation can seem daunting for manufacturers of software and devices. The requirements they face include:
- Ensuring compliance with legal specifications and norms
- Taking various target groups into account
- Finding a technical writer to create their documentation
- Managing, maintaining, and publishing this content
- Having the documentation translated, if applicable
Ticking all these boxes – and doing it well – is no easy task. At Lexsys, we’ve spent years helping manufacturers pull it off and would be happy to guide you through all the issues related to technical communication, from the costs and software involved to the actual creation and translation of your documentation.
Do you need support with your technical documentation? Contact us today to set up a consultation.
2 Responses
Dear lexsys.de webmaster, You always provide helpful diagrams and illustrations.
Hi lexsys.de webmaster, Thanks for the well-organized post!