How to write technical documentation

If you’re not a technical writer, but you are asked to create documentation, this quick guide will help you take the right approach. It is just 6 steps that will help you plan and structure your content, and avoid common mistakes.

Note that these tips are for documenting products and services. If you’re asked to write API documentation, you will need a different approach (although some of the principles are the same).

1. Think about who you are writing for

The first tip is to figure out who you are writing for. If you can’t ask customers directly, speak to anyone who deals with customers. Ask them about what problems customers have and what sort of terms they understand and don’t understand.

You can also use keyword research tools on the web to see what terms people are searching for.

2. Make a list of the tasks

Don’t write a description of a product’s features. That’s not going to be very helpful to readers. Instead, think of all the tasks a customer might need to perform. You could approach this by creating a list of ‘How to …’ tasks. That will be a good start, but when you write the content, don’t put ‘How to’ at the start of each topic, as that makes the content hard to use.

3. Use information types

If you’re not a technical author, it’s unlikely that you’ll know about content reuse features and information types. That’s ok. You don’t really need to know about them unless you have been asked to implement content reuse, in which case, you’re going to need technical writing or content modelling training.

But what you can do is write your content so that it is easier for a technical writer to work with in the future. The easiest way to do it is to break down the information for each topic into three sections — the concept, the task, and references.

Use the concept to explain the context. This is where you tell the reader when and why they should complete the task, and what the outcome should be.
Use the task to provide step-by-step instructions. Make sure each action is a separate step.
Use the references to include cross-references to any related information. For example, if there are a number of topics that need to be completed in a sequence, link to the next and previous topics.

In some technical writing tools, you can create these as separate files or topics. But if you’re using Word or a basic editor, such as those in Zendesk, just follow that structure in your writing. Start with the concept, then the task, then the references. It will work well for most types of documentation.

4. Use simple language

This is important. Technical documentation is not the place to show off your extensive vocabulary or vast technical knowledge. Write using simple language where possible and use jargon sparingly.

Don’t think of it as dumbing down. You are making the information more accessible to a wider range of people. Think of how newspapers present information — even the more highbrow papers use fairly plain language.

Remember that your reader doesn’t really want to read your content. They are using it because they need to solve a problem, so the quicker they can solve the problem the better. Simple language makes it easier and quicker to get the answers. It is also easier to translate and is less likely to confuse people who have English as a second-language.

5. Don’t write linearly

People don’t read user guides or help pages in a specific order. Don’t assume they have read ‘earlier’ sections.

One of the biggest mistakes I see with user guides is that they are written like a book where users read from front to back in order. Nobody reads a user guide or web help like that. People want specific answers and fast, so they need to be able to look up or search for a term, and go straight to that page. Importantly, the information on that page needs to be standalone, so that it makes sense in its own right (and links to other related pages).

If you do need the reader to know about other topics, link to them in your references section. But forget all about the concept of ‘earlier’ and ‘later’ in your user guide. Every page is potentially the first page, and you need to direct them from there.

6. Use a mix of short and long sentences

Lots of short sentences in quick succession can be hard to read. But long sentences are hard to read too. So to make your content more readable, try to aim for a mix. Two short sentences followed by a long one often works well. You don’t have to stick rigidly to that, just use it as a guideline. If a sentence is getting towards 20 words, think about breaking it into two.

Over to you …

Hopefully these tips will help you to create documents that are more accessible, consistent, and reusable. If you follow them and the work is later passed on to a professional technical writer, the content is going to be much easier for them to work with.

If you get stuck, you could try hiring a technical writer … there are freelancers out there willing to help (like me!).

Thanks for reading. I’m Craig Wright, a freelance technical writer in Chesterfield, UK. I help businesses by explaining how their products and services work, in terms their customers understand.