When it comes to writing a manual for your product, it all seems so easy. In the introduction you tell something about the product, you put a nice image next to it with a legend for the buttons or controls, and you start writing about how to use the product.
Easy, right? Finally, you check the technical manual of a competing product and conclude that you have created a successful manual. Quickly add a box with contact details, and job done.
Or is it?
There is much more to writing a good manual for users or installers. Just a description of the product, for example, is already insufficient by law. Even when describing the various steps to the user things can go terribly wrong.
In this blog you will discover the five classic mistakes that occur most often when writing a manual.
1. Complying with laws and regulations while writing a manual
The first one also sounds like the most elusive one. Laws and regulations? For manuals? What should the manual comply with exactly, and why?
The Machinery Directive
Every product that is brought to market must comply with the Machinery Directive. This a law that stipulates, among other things, that a user manual and a declaration of conformity must always be included. These documents guarantee a safe product within the specified standards.
But wait, a declaration of conformity? Doesn’t ring a bell. It will sound a lot more familiar when you describe it as a certificate with a CE marking. This certificate guarantees that the product meets all essential safety and health requirements. In short: a product that can and may be used safely.
And the manual itself, what does the Machine Directive say about that?
We can write long pieces about that because all required parts of a technical manual are mentioned in this directive. This means that not only the use (and the operation) of the product must be described, but also matters regarding:
- Safety;
- Intended and unintended use;
- Transport and storage;
- Assembly and installation;
- Commissioning;
- Malfunctions and how to solve them;
- Maintenance;
- Disassembly and disposal.
Only if all these issues have been addressed, you will know that your manual at least complies with all legal requirements.
The NEN 5509
Besides the Machinery Directive there is also the NEN standard for manuals, called the NEN 5509. The NEN 5509 provides regulations on the content, structure, and formulations within a manual.
When your manual is written according to the NEN 5509 standards, you can be sure that it meets the highest quality requirements and is perfectly usable for the intended end user. And that is ultimately the goal of every manual.
All our manuals comply with the Machine Directive and NEN 5509 standards.
In addition, we provide the Training course NEN 5509 and Machine Directive for technical authors in our Foxiz Academy.
2. Language
Language seems such an easy subject, but it is also something that turns out to be incredibly difficult when you start looking at the details. Even the most experienced authors regularly have headaches about language issues. Is this description really clear enough? Or could it still be misunderstood?
When it comes to language, a lot can go wrong in a manual.
Spelling and writing errors
This is of course self-evident. The use of flawless Dutch or English is paramount. Poor spelling or misapplied grammar not only make the manual look amateurish, but it can also cause instructions to be misunderstood. Moreover, an error-free translation of such texts becomes near impossible.
Sentences too long
Let’s be honest, if you look at it without thinking about it for too long, what do you really find easier to read when you think about instructions that are supposed to give an end user a clear picture of whether or not to apply safety measures before a product is put into use?
Theoretically, that was a correct sentence, but it is completely unsuitable for a manual.
Readability is key. In a manual, the ultimate goal is to make sentences as short and comprehensible as possible. Important information should never be omitted because that could in turn cause dangerous situations.
Language level
Another focal point is language level. If you use words that many people find difficult, you run the risk that the manual is not understood or worse, not read at all.
The Common European Framework of Reference for Languages is a directive to assess the level of language proficiency. Depending on the intended reader of the manual, it is advised to adjust the language level to the reader.
Want to know more? In the Foxiz Academy we offer the training course Writing Guide, in which we focus on all aspects of correct Dutch language use in manuals.
3. Written for the wrong reader
Everyone has their own expertise and hobbies. Within your own area of interest, you often know everything about every specific detail of that subject, including the related terminology. This is, however, very risky when writing a manual. What will the reader be able to understand when you write about tightening torques, gorders, WVGS or ppm?
Or the other way around: would you explain the use of a jack in ten easy steps to an experienced car mechanic?
When writing a manual, it is of great importance that your readers are always able to understand you, regardless of their background or knowledge. On the one hand, you must describe new subjects clearly. On the other hand, you do not want to frustrate professionals by extensively repeating assumed knowledge.
Some manuals are for general new users. Other texts are only meant for experienced and trained installers who really do know how to use all their tools.
In short: to know your target audience is an important starting point when writing your technical texts.
The training course Target Audience-Oriented Writing in the Foxiz Academy offers extensive information on how to match texts to the intended reader.
4. Incorrect use of images
Images make things easier, right?
Nothing could be further from the truth. We all know the visual instructions for the cupboards you can assemble at home. Step by step the images show you how to get to a good final result.
But practice shows that images might even be the most difficult part of a manual. It is a fact that you never need to translate an image, but to make one that speaks for itself is extremely complicated.
For this reason, instructions are always accompanied by images and vice versa. Text and images are the ideal complement to each other. True, a picture says more than a thousand words, but texts that describe what you see and what you can do with it are indispensable.
There are some ground rules for images to add value to your texts. We will mention a few of them.
Style
Make sure all images are made up in a similar style. Mixing photos, illustrations and line drawings makes things look messy. Choose one type of illustration and stick to that.
Format and position
Using different formats for images also causes a messy result. It is better to choose two or three standard formats for images in your document and stick to that.
A predictable position of the illustration on the page also provides peace of mind. For example, placing all illustrations on the left or centring them creates an orderly and consistent view. It doesn’t matter what you choose exactly, as long as your choice is followed through consistently.
Breathing space
Images and texts go most beautifully together as long as there is enough white space. Placing text too close to the image looks unnecessarily crowded. Every image needs ‘breathing space’. Determine how much white space you are going to use around images, and apply this to all images in the document.
Captions, legends, and markings
An illustration becomes even more useful when it is accompanied by the needed information for clarification. You will help make it easier for the reader to understand everything.
Three points of interest that are all too often forgotten are captions, arrows, and legends.
A caption is a short text below the image that describes what is shown.
A marking is a line towards a certain part of the image, with a unique number. You can then conveniently refer to this image and number in the text. This is the most powerful way of explaining.
A legend shows where specific numbers from a pointer refer to. These are especially useful for giving an overall view of a product before delving into the details.
Too many or too little detail
The clarity of an image in its first impression is central to its comprehensibility. An image with many details – which are not needed at that moment – is not effective. Always keep in mind which subject is being discussed and what level of detail in an image is optimal at that time. In this way, you create an ideal combination of text and images that reinforce each other.
Images are a speciality. For that reason, we offer technical writers an extensive training course Visual Language in our Foxiz Academy. In this training course, you will get to know all building blocks and finer points about how to use images perfectly in your documentation.
5. Layout and scannability of your document
A text must invite to read. Texts that look pleasant all have one thing in common: Attention has been paid to layout, structure and scannability.
How do you write a text that looks attractive?
Clear chapters and paragraphs
To start with, you choose a chapter structure in advance.
Within the chapters, you use sections. And within sections, you apply paragraphs. Do not forget to limit the number of sentences per paragraph to at most five short sentences.
With this layout you build a text that provides sufficient breathing space between the various parts. Blank lines between paragraphs, sections and chapters are comparable with breathing space between the sentences you pronounce. You don’t babble on, but you take a break every now and then. The same goes for texts on paper.
The main advantage of applying chapters and sections is that your document becomes easier to scan. If someone is searching for a specific topic, they can easily and quickly find it by looking at the chosen headings.
Do not forget the numbering
In several places, numbering is indispensable: in all headings and on every page.
Especially in technical manuals and other technical texts it is essential that the reader can quickly find what he or she is looking for. Therefore, with each caption (of chapters and sections), in addition to the titles, apply ascending and logical numbering. This way you take the reader through the document. Page numbering is a logical addition as well.
Table of contents
When you have chosen clear titles and applied numbering and captions with images, an index is the next logical step.
Every manual needs a table of contents or an index. Most word processing programmes can generate these automatically. But did you know that you can also make a table of contents of images or tables? For specific search requirements, this gives the reader even more overview.
MS Word is your friend
In word processors, such as Microsoft Word, there are many layout styles and possibilities to improve your document. Everything about titles, captions, layout, numbering and whatever else you can think of you can find in this software.
For a detailed look at the many advanced options that make formatting documents easier, Foxiz Academy offers a training course Microsoft Word.
6. Conclusion
Although writing a text seems so easy for a user, there is still more to it than you would expect. If you follow the legislation and regulations, you are legally safe. Additionally, it is important to work consistently in your document: Keep it simple, clear, and uniform, without overlooking important details.
By applying these basic rules, you have a firm basis for a document that impresses the reader and reaches its goal!
Want to know more?
Do you want to know more about the profession of technical writer? Foxiz can help. Not for nothing our motto is ‘Foxiz makes technology understandable’. The Foxiz Academy offers various training courses for the (beginning) technical writer. On our website you can find all information about this.
About Foxiz
The Foxiz team consists of project managers, technical writers, technical illustrators, and translators who like to go the extra mile. We produce documentation for safe and correct operation, for maintenance tasks and for assembly and installation. We can help with all your questions and will gladly take care of your technical documentation and translations.