How to write technical documentation - quick guide

how to write technical documentation

In some organisations, the job of creating technical documentation falls on a non-writers desk. Obviously, I don't approve of that approach, as technical writing is a specialised type of content writing. But sometimes it can't be avoided. With this quick guide, I'm going to try and help non-tech writers do a reasonable job.

The guide is just 6 steps that will help you to plan and structure your content, and write it using suitable terms. Following them won't make you a technical writer, but it will help to keep your documents more consistent. And it will make it easier to for a technical writer to use your work at a later stage, if your organisation goes down that route.

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 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 task 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 tasks that need to be completed in a sequence, link to the next and previous tasks.

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 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 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

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.

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. But 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 ...

If you're faced with writing technical documentation and you're not sure where to start, hopefully these tips will put you on the right track.

If you get stuck, you could try hiring a technical writer ... there are freelancers out there willing to help :)

Craig Wright technical author

Craig Wright is an experienced technical writer based in Chesterfield, UK.  He hates writing about himself in the third person, so I shall stop now.

Always interested in new content writing opportunities. Remote working preferred.

Email help@straygoat.co.uk
Phone +44 07954141761

Straygoat Writing Services Ltd
26 Wheatlands Road
Wingerworth
Chesterfield
Derbyshire

Registered Number: 08029184

Straygoat logo design by Bristol graphic designer, Nik Jones.

© Straygoat Writing Services Ltd.