Want to know more about technical writing? Check out our 5-step approach to technical writing in this article.
What is technical writing and what does a technical writer do? Have you ever had to write an instruction manual and struggled with how to proceed? Well, let’s begin with the assumption that any technical document —whether it is a datasheet, a technical report, or an API guide— serves one purpose: informing the user. All kinds of technical documentation (e.g. operating manuals, handbooks, technical reports, etc.) are part of the product itself. Therefore they must be user-oriented as part of a whole content strategy inside the organization.
The process of writing is a complex one, but here you can find the five main steps with useful tips.
1. Collecting info — the first step in the writing process
This step consists in collecting every piece of information you can find about the product you are about to describe. This is the most important part of the process because all the subsequent steps and the whole content rely on this preliminary phase.
During this phase, you must carry out an in-depth analysis of the content and the context. For instance : scope, schedule, the legal framework of the target market, audience, and last but not least, the product and how to use it. This means:
- Interviewing SMEs (Subject Matter Experts) and stakeholders. Ask questions to all those who are involved in the development and design process, in order to gain knowledge about the product and the subject matter as well as any applications and features.
- Studying contracts and specifications. Any technical document must comply with the applicable legal requirements, mainly dealing with product safety, so read them all thoroughly and carefully.
- Accessing the risk analysis. Use this internal document to write your technical documentation and draft correct safety warnings and instructions for use.
- Analyzing your target group of users. This task aims to produce an understandable technical document tailored to the need of your potential readers, in terms of language, type of output media, and graphics.
2. Writing needs structure
During the structuring phase, you will create a well-defined Table of Contents. You need to dedicate time to establish a clear structure because this will be the backbone of your writing journey. However, you should be prepared to modify it along the way, as some fine-tuning may be needed.
3. Drafting —put into practice your technical writing skills
This is the step where you really get into action. As a technical writer, you must always consider the user, and adopt an action-oriented — or “task-oriented” — approach, bearing in mind that your reader is a user who is looking to accomplish a task. Also, always keep an eye on your style and use writing techniques suited to a possible subsequent translation.
Opting for Simplified Technical English as a powerful writing tool
Originally developed to make maintenance documentation for aircraft and their components easier to understand for a global audience, ASD-STE100 Simplified Technical English (STE) is a controlled language standard. It helps to improve readability and translatability of technical documentation.
Among the syntax rules, note the use of:
- Active voice
- Simple verb tenses
- Simple sentence structure
- Term consistency
If you are curious and want to learn more, check out this article about the benefits of STE.
4. Submitting your technical documentation for review
One may be tempted to skip this step, but this is actually a crucial phase. Always submit your draft to the Subject Matter Experts (SMEs). There are two reasons to do this. Firstly, as a technical writer you always need to validate the content of your writing. Secondly, you want your text to be free of errors such as typos or grammar mistakes. Another set of eyes is always great support.
Once your content has been updated with remarks and corrections implemented, you can proceed to the DTP (Desktop Publishing) step. You should carried this out at the very end of the process, to avoid unnecessary reworking of layout and formatting.
To wrap up
Writing technical documentation may be seen as putting together building blocks to shape an effective and coherent structure.
As further reading, I suggest checking out this interesting article about small but useful tips to survive as a technical writer.
Did you like this blog post on how to write technical documentation? Share it on Facebook, Twitter, or LinkedIn.