Imagine explaining the use of Excel and all its functions to someone who has never worked with the program before – in a written manual. Where would you start? By explaining how to open the spread sheet program perhaps, followed by the question how to create new documents, formulas or analyses. How would you make sure that your pupil understands everything? With the help of step-by-step bullets, screen shots or images for example?
It’s a simple example of the questions a technical writer has to deal with on a daily basis. And not only technical writers, but every person who’s involved in writing documentation on (complex) technical processes, like reports, processes or manuals. Technical writing means writing something down that everybody within your target audience should be able to understand – regardless of his or her training or background knowledge. But why is that so important? And what are the best practices when it comes to technical writing?
Minimise the risk of human error
There are two main reasons why technical writing skills are so important. First of all, when working in highly regulated environments, including those that involve pharmaceutics, biotechnology or medical devices, you need to make sure documents are clear for your target audience. If processes are clear and not liable to misinterpretation, you can minimise the risk of human errors and thus guarantee a more qualitative process. Secondly, thorough documentation is crucial in case of audits or errors, to explain and analyse what steps were taken, what went wrong and what was the right approach, for example. This means that technical documents or manuals should not only include the steps towards a certain result, but also the steps to be able to explain that specific result. In addition, these documents should be suitable for use over a longer period of time, up to five, ten or even twenty years.
Technical writing: do’s and don’ts
Whether you are a technical writer or not, there are some rules of thumb to keep in mind when you are involved in technical documentation.
- Don’t expect prior knowledge: a well-known pitfall for technical writers is assuming that your target audience already has prior knowledge about a subject. Don’t refer to other things, or skip certain steps, just because you think it’s evident.
- Vary between text and visuals: if your target audience needs to click on an icon, it’s much more efficient to implement a visual of that specific icon, instead of describing this step in several sentences. In general, visuals are less liable to misinterpretation than textual information.
- Use everyday, simple language: try to be as clear, direct and neutral as possible, and always keep your audience in mind. If possible, plan a review phase with somebody from your target group to find out if your document is accessible enough. And avoid using technical jargon.
- Pay attention to structure: for example by using bullet points to sum up various steps in your process. You should also make sure to use readable fonts and a clear, professional lay-out. If you’re writing larger documents or manuals, consider adding a table of contents or addendums.
- Review your document: creating technical documentation is often an ongoing process. Make sure to frequently review your documentation to stop small errors from creeping in and guarantee faultless information.
Learn more about technical writing
Fortunately, technical writing is not a rocket science. It’s all about using your common sense. However, we should be aware of the importance of good technical writing skills. That’s why QbD offers practical training in technical writing. Including exercises, typical pitfalls, discussions and a lot of examples. Because we believe that everybody possesses the basis for technical writing skills.