9 technical writing tips every writer should know

Technical writers have a difficult job, taking the complex and making it comprehensible for users. Technical writing might be your main job or it may simply be one of your duties as part of another role. Technical documentation is important for making products more user-friendly and enabling users to get the most out of your products. 

Writing technical documentation is a process and takes time to get right. It’s unlikely that your first draft will be ready for your audience, and that’s nothing to be ashamed of. Many hands make light work and you should be producing your documentation as part of a team, with coworkers able to help you create a final draft. 

1. Research your users

In technical writing, it’s extremely important to know who you’re writing for. The documentation is intended for use by real people and you can find out who they are so your writing is relevant for them. 

It’s important to understand what your audience already knows about the subject so you can pitch your documentation at the right level. At the same time, you don’t want to patronize your audience with too many details if they already have a good foundational knowledge of the subject area. 

Conducting user research groups is a good idea so you can really get to know your users. Ask these questions:

• Who are your users? 

• What do they want to get from the documentation?

• What are the prerequisites for understanding the docs? 

You’re likely to find a lot of variation in your users and this will have to be reflected in your technical writing. 

2. Create an outline for your document

People are likely to be coming to your documentation when they are already lost and confused. Structuring your document properly is the best way to provide assistance to your readers in their time of need. 

Before you start writing, create an outline for your document that will help you structure your article. It will help you think through your content much more effectively and you can make sure the steps are laid out in a logical order. 

When thinking of your outline, make sure you split your document up into different sections with headings that clearly explain the content of each section. 

3. Use plain language

Using “technicalese” is one of the curses of documentation – you might think your writing is easy to understand but readers are left scratching their heads. 

Plain language is the cornerstone of good technical content. Split your long sentences up into short ones and choose simple words instead of complex terms. If you must use a technical term, include an explanation and make sure you explain all acronyms. 

Use unambiguous language so readers will definitely understand your writing. Instead of saying “Add a little bit of water”, say “Add 50 ml of water” to be more precise. 

4. Use active voice

Your documentation should be clear and immediate. You must get to the point as swiftly and cleanly as possible, and to do that you need to use active voice rather than passive voice. 

Active voice means that the subject of the sentence is acting upon it’s verb, while passive voice means the subject is the recipient of the verb’s action. 

When the subject of the sentence is performing the action, we say that it is written in the active voice. 

Instead of saying, “The button must be pressed by the operator” you should say “The operator should press the button.” 

5. Cultivate empathy for your audience

When writing technical documentation it’s easy to get lost in the forest and not be able to see the wood for the trees. You become so close to your writing that it’s easy to forget that you have an external audience, who are likely to be confused and stressed when turning to the documentation. 

Periodically remind yourself of your audience and step into their shoes for a while. How would your audience interpret this particular sentence? Is it easy for your audience to understand this sequence of steps? 

Remember, your audience is not your enemy. Writing clear and helpful documentation is part of building a relationship with your audience and ensuring they continue to derive value from the product. Empathizing with your audience means being sensitive to their needs and making sure you produce the best documentation possible. 

6. Use examples in your writing

Wherever possible, use real-life examples in your technical writing to illustrate the concepts you are trying to explain. Examples keep your documentation linked with reality and that’s helpful because technical writing deals with practical matters. 

If you’re writing an online user manual then some of the points in your text are going to deal with a situation where things have gone wrong. Use realistic scenarios to show what the reader might encounter – for example, if you’re writing a manual to explain a piece of equipment, use an example to explain what the correct parts in the right position would look like. 

7. Include relevant images

Ideally, your documentation shouldn’t just be a wall of text. Sometimes, you can get across an idea more effectively using the power of visuals rather than words. 

Whatever kind of technical writing you’re doing, include relevant images to bring your words to life and better explain the point you’re trying to get across. That could be graphs, diagrams, screenshots or even videos. 

It’s important to remember that some users will be using screen readers to access your documentation, and visuals won’t be read out. Your documentation should still be understandable by someone reading the text, and the visuals should support your point rather than making it for you. 

8. Get SMEs to review your content

When you’ve written your content it’s crucial to check it for factual accuracy. This is where your subject matter experts come in. 

Leave enough time in your content review process for an SME to check your work. Send them an email clearly explaining the type of feedback you’d like for your documentation – ideally at this stage it isn’t punctuation and grammar checking. You’d like your SME to check the documentation is a correct and truthful representation of the product. 

SMEs are often pressed for time. Allow up to a week for their review and thank them for their contribution, maybe with cookies. 

9. Hire a professional editor

You shouldn’t be editing your own work yourself. It’s so easy to miss glaring errors and flaws in the documentation because you’re so used to your own writing. You understand the point you were trying to get across but it may not be so obvious to others what you meant. 

If you have the budget for it, hire a professional editor to proofread and edit your work. They will be able to make your writing more accessible to users and bring clarity to your words. 

Final remarks

Good technical writing is not easy but it’s certainly achievable if you follow these tips. From carefully planning your documentation with an outline, to cultivating a deep understanding of your users, to a rigorous review process, you can write documentation that is both clear and helpful to users.