Become even better at writing technical documentation

FOLLOW US ON LINKEDIN

At World Translation, we think user manuals and other kinds of product information are extremely interesting and very important documentation. Let’s be clear about this – without user manuals to help your customers, how else would they use and understand your products? What could be more important than that?

– Do you need to write a product manual but do not know how to tackle the project properly?
– Does your company have user instructions that need upgrading and polishing?
– Do you want to know what format is best for your Quick Guide or whether your manual complies with the Machinery Directive?
– Do you know what you need to keep in mind when your production documentation is to be translated, so your product can be exported?

We answer all of these questions and more in our “8 Good Habits” article here on the blog.

1:Use communication to create an excellent image!

Technical documentation is a general term that describes all types of advanced sales and post sales documentation.

Technical documentation is written communication about the company’s product between a company and its stakeholders – usually the end users. User manuals, instructions, guides and data sheets are typical examples of technical documentation, and each of these communication tools has its own characteristics. Often companies make user manuals that describe how a product works, rather than tell a user how they should use the product.

Good documentation helps to ensure customer satisfaction and contributes to the machine manufacturer’s image as a professional supplier. Poor documentation, which can be misunderstood by the recipient, may result in the product and the company being rejected in favour of another company, and in the worst case, lead to a lawsuit.
Remember these four elements when you prepare your documentation, so you can avoid poor experiences:

2: Know your DTP program

DTP is an acronym for Desk Top Publishing. As the term indicates, it is about publishing texts using a desktop computer.
Word processing programs can deal with continuous text but they are not very good at dealing with pictures. Image editing programs are good at processing images, but normally they are not very good at word processing in or around images.
Use the correct DTP program for your document tasks. You will save huge amounts of time and avoid a lot of frustration.

Both Adobe FrameMaker and Adobe InDesign can deal with “books”. This means that a document can be built up as smaller, independent chapters, which at the end of the process, are put together as a single book.
Among other things, this makes updates easier because only the individual chapters need to be updated – there is no need to update the whole document.

Standard text tasks:

For small, simple tasks, use a standard word processing program like Microsoft Word or an equivalent program. Word processing programs can also be used to create technical documentation, but it presupposes the user has detailed knowledge of the program’s options. If you have large volumes of documentation or need regular updates, it is recommenced that you use a “genuine” DTP program, such as Adobe InDesign or Adobe FrameMaker.

Small/medium large tasks:

Adobe InDesign is a specially developed DTP program, which is particularly suited to documentation tasks that have many graphical elements, such as sales brochures, marketing material, Quick Guides, etc.

Medium large/large tasks:

The DTP program Adobe FrameMaker is very well-suited to working with large volumes of text and illustrations.

Other programs, such as CorelDraw, Microsoft Publisher or CAD programs should be used with caution when dealing with document tasks. If your documentation is created in one of these programs, it may result in extra costs for updates, and many translation applications do not work well with them.

3: 80/20 Rule

The 80/20 rule, also known as the Pareto principle, is a tool that both companies and individuals can use. The 80/20 rule states that for many events 80% of the effects come from 20% of the causes.
In other words when it comes to work, 80% of your results are due to 20% of the time you spent working*.
The 80/20 rule is also a good way to describe how typical documentation projects interrelate. The general rule of thumb is that 80% of the time spent on documentation projects is spent on planning. Only about 20% of the time is spent on producing the actual documentation. Planning is the foundation of the entire project. It is vitally important, but unfortunately it is not as visible or measurable as the actual writing.

Information searching:

  • Choose your sources of information with care. Consult with customers, experts, developers, etc.
  • Make a checklist of all of the information you require.
  • Ensure that you get the information in time.

Target group:

  • Assess who the documentation is for. Your documentation should be written to suit the target group.
  • If required, make a Style Guide, which is a set of standards for the writing and design of your company’s documents.

Layout:

  • Ensure that your documentation is easy to use, including a manageable page layout and a good table of contents.
  • Ensure that your document has the same quality as the company’s other documentation.
  • If necessary, use illustrations to clarify the instructions.

Language and tone:

  • Remember these are instructions you are writing – not a letter or a story.
  • Avoid slang and esoteric language. Don’t know what esoteric means? That’s exactly what we mean!
  • Use the same term for the same thing throughout the entire document.

Companies pay a high price for poor documentation
Most people know how difficult it can be to follow the instructions that come with a product. The joy of getting something new and exciting is completely ruined by problems getting it to work properly. Some people give up. Some people use trial and error. Those of us who are more persevering, contact the store or company from where the product was purchased. Regardless of the cause, this kind of problem has a negative impact on the product’s reputation. No one ever recommended a bad product to a friend or associate. Poor publicity is toxic for a manufacturer. In a global world, where many companies rely heavily on exports, the consequences can be catastrophic. Ultimately for some companies, it can mean the difference between life and death.

IT PAYS TO INVEST IN GOOD DOCUMENTATION AND TRANSLATION.

4: Use of standards when preparing documentation

Machinery Directive
The preparation of documentation is generally based on a set of rules. This article is based on documentation that must be prepared in accordance with the Machinery Directive 2006/42.
The Machinery Directive lays down a number of requirements related to the safety of the design and construction of machines. For a machine to be able to be marketed in the EU and the EEA, it must meet the requirements in the Machinery Directive. In other words, a machine may not be marketed if it is not safely designed and constructed.
In addition to these safety requirements, the Machinery Directive also lays down requirements for the accompanying documentation. The user manual must always be supplied in the language of the country the machine will be used in – this applies to EU and EEA member countries. This is a compulsory requirement. Only the maintenance instructions may be supplied in another language, and only where the maintenance instructions are used by the manufacturer’s own personnel.
The directive also lays down requirements for the contents of the user manual. These are found in appendix 1.7.4.2 of the Machinery Directive and they apply to all user manuals. Depending on the type of machine, the Machinery Directive lays down other requirements. For example, a machine that is used to make food must have cleaning instructions.

Standards
The Machinery Directive is the law when it comes to the design and construction of machines. Standards have been devised as Machinery Directive guidelines. These may be considered as interpretations of the Machinery Directive. A standard may cover a single safety aspect, like an emergency stop or row spacing, and at the same time also cover a specific machine type, e.g. a meat cutter. Using the standards is not compulsory – you are permitted to use your own solutions. However, the overall safety level of the machine must be maintained. This means that as a minimum, your own solutions must be as safe as those that are stated in the standard. The same applies to the contents requirements for documentation.
In addition to the requirements related to the safe design and construction of the machine, the standards also lay down supplementary requirements for the machine’s documentation and user instructions. This means that you need to know the basic requirements in the Machinery Directive, as well as the supplementary requirements in the used standards. If a machine is equipped with a wire emergency stop, the user manual must instruct the user in how to carry out an inspection of the entire length of the wire emergency stop before the machine can be re-started.
The task of the documentation professional, is to find out which directives are relevant and which standards are used, if any. The information about directives and standards is usually collected together and kept in a company’s design department. We recommend that you find out which directives and standards apply even before you begin the design phase, because this will ensure the machine is designed and constructed correctly, and documented correctly. It will always be advantageous if you keep a version of a basic user manual that complies with the Machinery Directive. The task thereafter, is to integrate the requirements from the used standards, to ensure that the documentation meets the relevant requirements. Not only does a good user manual meet the formal requirements in the directives and standards, it protects the manufacturer from making a machine that causes accidents.
Author: Thomas Thillemann Petersen, Department Manager at Maskinsikkerhed ApS, a business partner of World Translation..

5: When the product is supplied

Anyone who works with documentation knows how important it is that the documentation is made as user-friendly as possible. But that’s not all.
A document management system does not need to be expensive, complicated or resource-demanding. Often, an EXCEL sheet is sufficient. The most important thing is that it provides a good overview of the company’s documents and that it is easy to maintain.
It is just as important to have a document management system. The system must be able to manage documents throughout the entire lifetime of the product, from the moment the product is supplied, during the period when the product is used and users and other stakeholders provide feedback, to the day when the product is not longer operational.
It is important for both the seller and customer that: ∙ The correct documentation is supplied with the product. ∙ The documentation is traceable, so that it always refers to the same type and version. ∙ Internal resources are allocated to dealing with customers’ questions.
Regardless of how good the documentation is, it cannot describe everything.

The figure below illustrates a typical lifecycle for technical documentation:

Tips & tricks
  • Start creating the technical documentation well before delivery of the product. Documentation that is created at the last minute, runs the risk of being incomplete or containing errors.
  • Create a system for documentation management.
  • Prepare any documentation that needs to be translated.

6: Outsourcing — the way forward

Outsourcing is the process when a company chooses to purchase services from a supplier – services that the company had previously managed in-house. Outsourcing has made many inroads in the last few years, and nowadays a lot of companies need to outsource to remain competitive.
For a lot of manufacturing companies technical documentation can be a thorn in their side. It takes time and expertise to write, and who really wants to read it anyway? But errors and deficiencies in documentation can prove to be very expensive for a company when something goes wrong, and the consequences can be serious. A company can outsource the documentation tasks to a specialised agency as a way of reducing their workload, lowering labour costs and ensuring the correct competencies are available for their technical documentation.

WHAT DO YOU GAIN FROM OUTSOURCING?

Use your resources in the best possible way
Let your employees focus on their core competencies and let the agency’s experts deal with the documentation tasks.
No fixed salary costs
Of course a consultant must also be paid for the work they perform, but only in the period when the project operates. There are no fixed expenses for office facilities, insurance, holiday pay, etc.
Gain a strong partner
With mutual trust, a brilliant collaboration can be created for the exchange of know-how between your specialists and the documentation experts.
Of course outsourcing means that you need to introduce a consultant to your product, your work processes and much more. But when that part of the work has been done, the consultant can take over the documentation work.
We can help you with the translation of your technical documentation. Read more about our translations.

7: Entering the global market

Some companies view the export of their goods and products as a long-term possibility, while a great many companies start to export their goods and products more by chance than by any deliberate action. There are a great many things that have to be considered, before you begin exporting goods and products. When it comes to technical documentation, it is important that it is tailored to suit the new market. Perhaps the layout needs to be changed, the language changed, or a completely new type of documentation has to be created.
When it comes to exporting machines, the documentation must comply with local market regulations in Europe, including the EU Machinery Directive. This specifies which documents must be supplied with the machine, and in which form the documentation is to be delivered. There are corresponding standards for other industries.
Here are a couple of examples to illustrate how your technical documentation can avoid pitfalls.
Example 1)
A Danish manufacturer of salt spreaders recommends that salt is used in its machines in Denmark. In Norway, where the ice on the roads is harder, and icy conditions last longer, salt has no effect. In fact, salt will often only melt the surface layer of the ice, creating water on the road, making the road even more slippery. This means that the text of the Norwegian manual needs to be edited to ensure that the correct material is used in the salt spreaders – so the manual’s content now matches the Norwegian circumstances.
Example 2)
In Denmark, we often associate the colour blue with peace, calmness, harmony, trust and selfconfidence. In other countries, the associations are different. In Columbia, the colour blue is associated with soap. In the Middle East, it is seen as a protective colour. In China, it is associated with among other things, immortality, and in Jewish culture, the colour is associated with holiness. The wrong colour can result in countless cultural misunderstandings, which in the final analysis can damage a company’s exports. So there are good reasons for considering the use of blue and other colours in your technical documentation.
Example 3)
The wrong formatting can lead to an error in the translation of your manual. When a text is translated using a CAT application, the text is divided into smaller segments. The segmentation is based on punctuation, formatting and codes. If a sentence is divided up into several segments, because of incorrect formatting, e.g. an incorrectly placed line change, an error can happen in the translation, because the sentence can be misunderstood, or gain another meaning. So you have to be very careful with punctuation and formatting when you write your technical documentation.
You can save a lot of frustration when exporting to foreign markets if you think about the potential pitfalls beforehand, and actively do something about them when you are preparing your technical documentation. This may mean that you have to put some extra effort into finding out about colour associations, or the local circumstances, before you start exporting. By doing so, you will avoid unpleasant surprises like your product being rejected because the manual contains errors as regards content or a work accident in a foreign country because the translation contains errors due to wrong formatting.

8: The world is your customer

Scenario 1:
You have sold your machine to a buyer in a foreign country. At last – you have started to export your products! But the buyer requires that your manuals are written in their national language, and they will only receive your machine once all of the information is written in their language. What do you do?
Scenario 2:
You want to sell your products online. Your website is in English, but you are simply not selling enough of your products abroad. Do you need more than just an English language version of your website?
Professional translation is the solution to these problems
When you sell your machine inside the European Union, you must comply with the EU Machinery Directive. This stipulates many things, for example that technical documentation which accompanies the machine must be written in the national language of the receiving country. The buyer has the right to refuse to take the machine if the documentation is not available in the correct language. However, translating your material is not just about complying with regulatory requirements. A study by Common Sense Advisory* has shown that online shoppers prefer to use websites written in their own language. 52.4 % of consumers first purchase products online, when the website has been translated. They are even willing to pay more when the information is in their own language. In other words, translating your website can help to increase sales of your products.

Download the 8 habits as a PDF:

Vane 5