Writing technical documentation How do I get off to a good start in 8 steps?

Writing technical documentation

How do I make a good start in 8 steps?

Most people who start writing technical documentation for a product, service or software package are inclined to do this with a tool from Microsoft and Adobe. And mainly with MS Word and InDesign from Adobe.

Basically there is nothing wrong with that when it comes to a simple document.

Seasoned Word users know how to produce the most beautiful documents, decorated with photos, AutoCAD cutouts and diagrams. The layout is then done in, for example, InDesign. The results are impressive.

We at Author-it don't want to discourage this creative process, but we do give you a few things to think about.

Consider the following;

• Where does the content live after it has been created and is it safe there?
• Where do you adjust the content, and do you also have to work on the layout again?
• How do you manage the different versions?
• Can someone change it, whether desired or not?
• Do you want to, and can you, put so much energy into this creative process every time?
• Does it need to be translated? And how many languages?
• In addition to PDF and print, would you also like to use this (adapted) documentation for another medium?
• What happens when the workload becomes high, how do you divide the work?
• Can employees participate in the documentation process?
• What happens if the writer leaves the company?

Anyway, back to what it's really about, making technical documentation readable.

1-Define your target group

The approach and composition of a text depends on the target group. This seems very obvious, but as a writer you have to read back again and again with the reader of your document in mind. Listening to your target group, analyzing, understanding, asking questions and selecting are essential in this step.

2-Write the technical documentation

Try to use a template so that you can act logically. It is pleasant to work when, as a writer or participant in the writing process, you do not have to think about the layout, layout and structure. Try reapplying previously used text blocks. This speeds up the writing process and ensures consistency of the texts. And last but not least, it significantly reduces translation costs. 

Technical communication continues tekom Europ , the European organization for technical writers, defined as the arts of being able to accurately, correctly and effectively convey factual information to certain target groups for specific purposes.

3-Simplify and reduce the texts

Even if you think you know your target group well, prevent the reader from dropping out or misinterpreting the text. For example, use few or no abbreviations.

When you prepare texts in English, use Simplified Technical English (STE). This is a useful tool to eliminate redundant, difficult and confusing words and phrases from your technical documentation.

Some technical documentation is only read during an emergency. (How do I operate the fire extinguisher?) Lengthy and vague texts should be avoided. Describe something punctually. Use action items or numbers and keep it short.

4-Determine the content of the technical documentation.

Before you start writing the technical documentation, it is important that you have collected all the information from the experts. Then, the purpose of technical documentation is to tell the user how to use the product safely and correctly.

In the EU there are guidelines/standards for user manuals.

Writing user manuals (NEN5509)

To meet the requirements of European directives and standards, must companies create documentation. What needs to be made is;

• The declarations of conformity.
• The user manual.
• The technical (construction) file.
• Work instructions for your own machine park. 

And in general there are issues that appear in every technical documentation.

• A description of the product
• Technical specifications
• Precautionary measures
• Instructions for installation and commissioning.
• Maintenance, malfunctions and defects

5-illustrate the technical documentation

By adding photos or illustrations that support or replace the texts in your technical documentation, the time it takes for a user to learn something and act correctly can be greatly reduced. The amount of text is reduced and partly replaced by images. This not only makes the technical documentation more pleasant and interesting, but it also reduces translation costs.

6-Translate the technical documentation

In many cases, technical documentation also needs to be translated. Sometimes this is done purely to comply with legislation, or because it promotes a user-friendly transfer of information. Regardless of your reasons for having your technical documentation translated, it is important that you engage a translator or translation agency that has the necessary knowledge and expertise in translating technical documentation.

In any case, the translation agency should support a translation memory of your content and have knowledge of localization. The latter is important for the context in a particular language.

7-Prepare the technical documentation

Once the content of your technical documentation is ready, it is time to neatly format everything and provide it with the correct design. Commonly used software programs for creating technical documentation include Adobe InDesign, or FrameMaker, or the more specifically designed,  Author-it and MadCap Flare.

8-Publish the technical documentation

Providing a paper manual is mandatory for most products.

However, this obligation can also be an advantage. For example, a company with good documentation has a much better position in claims and other legal issues.

It can also be an advantage to make a digital manual available. These types of manuals, usually in the form of a customer portal or a customer service center, offer the user the opportunity to also consult the technical documentation via computer, tablet or smartphone. The big advantage is that as a supplier you can adjust the information and provide video instructions and animations.

But there are more advantages such as;

• An image improvement.
• Satisfied customers.
• Good reviews.
• A less burdened service department.
• Faster transfer and availability of information.
• More convenient and better training of new employees.
• A safe working environment with safer machines.

Author-it has a Dutch office and team of experts who can advise you on purchase, use and optimization.

Go for more information about Author-it and a demo to our website.  Fill in your details and we will contact you quickly from the Netherlands.