How to write technical documentation
Some rules and principles needs attention
When writing technical documentation, please take at least three principles into account. But before applying these principles, it is important to know which legal requirements should be met in your manual.
When is technical documentation needed?
It doesn’t matter whether you are looking for a technical manual for an airplane or for a more down to earth manual, let’s say for a vacuum cleaner. In both cases, European directives tell you that
1. you cannot sell your product without a manual and
2. your manual should meet certain legal requirements .
What’s more: according to almost all national and international regulations, technical documentation is a part of the product itself. As a consequence, a faulty manual could imply a faulty product. Which could lead to the issue of accountability if your technical documentation is not up to standard.
What should be in your technical documentation?
Given the European directives and legal requirements in other parts of the world, technical documentation is not complete without:
- technical specifications,
- safety instructions,
- installation procedures,
- problem solving procedures,
- environmental issues.
Experts like Manualise know exactly what should be in your manual.
What to take into account when writing a technical document?
Writing a technical document is work for experts. For documentation writers, it is important to have analytical skills, to be very quality driven, to be very curious and to feel comfortable in any social setting. Last but nor least, they should cherish their eye for detail.
Documentation writers should not shy away from any challenge. Which are these challenges?
- Collecting as much information as possible;
- Leaving themselves out of the picture if a picture can say more than a 1,000 words;
- Using sophisticated content management software for technical documentation;
- Knowing what the tone of voice should be: do writers address an expert or someone completely new to the product or service?
Also, it is important that documentation writers feel completely at ease when it comes to the main principles of writing technical documentation. These principles are Simplified Technical English (STE), minimalism and topic based authoring.
Simplified Technical English
Take the following sentence: “Turn off engines not required”. What is the meaning of this sentence? Does it mean ‘Turn off the engines that are not required’? Or is the meaning perhaps ‘Turning off the engines is not required at all’? STE provides rules to prevent this kind of ambiguity. Basically, STE consists of a set of rules, limiting the number of words in a sentence and restricting the set of the words permitted. For example, ‘to do’ is much simpler than ‘to carry out’.
If you have to fill up oil, it is not necessary to know the reason why. This implies that you do not need to provide background information when immediate action is the only thing that counts (“1. Take the black bottle, 2. Fill up the engine with oil”).
This may sound unfriendly to the reader. After all, we all want to know what we are doing, not only how we are doing it. But one can give background information elsewhere, for example, at the beginning of a chapter. Also, direct action is often of the utmost importance. When a pilot is losing pressure in his plane, he does not want his manual checklist to say: “Check valve A, then valve B and after that valve C.” He wants his checklist to say: “Put on your oxygen mask immediately.”
Topic based authoring
In technical writing, topic based authoring is everthing. What is topic based authoring? Topic based authoring is nothing more (but certainly nothing less!) than dividing information into functional blocks. These could be blocks like ‘Maintenance’ and ‘ Safety’. By using this topic based approach, it is very easy to reuse information. This is, of course, precisely the point.