Ten tips for writing a user guide

As a freelance technical writer, I collaborate with teams at several different companies – usually a mix of product managers, developers, support staff and field application engineers. It’s always enjoyable getting to know people and hearing about their lives both at work and outside it. However, the nature of my role means I come in and out of organizations as and when they need me.

After a while, I realised that having some more long-term “colleagues” is also important. To meet that need, I now have regular coffee dates with a few fellow freelancers. Whether it’s sense-checking a new workshop approach, celebrating a new client, or just sharing weekend plans, we all benefit from the camaraderie.

Recently one of those “colleagues” asked me for some tips on documentation. Specifically, he asked if there was any received wisdom on writing user guides that he could share with someone else working on his project. “Plenty!” was my response.

That conversation reminded me that while these principles feel obvious to me, if you aren’t a technical author then there’s no reason why you should know how to write a great user guide.

So, for anyone new to technical documentation, these are my top 10 tips for writing a user guide.

1. Begin with your audience

Start by asking yourself a couple of questions. What is your target user trying to achieve when they come to use your product? What sort of job role is the user guide aimed at? Understanding your target audience and building empathy for them should inform every decision you make, from what to include in your user guide and how to structure it, to where you publish it.

2. Clarify the goal at the outset

This probably won’t come as a surprise, but most people don’t read technical documentation for fun! Your first goal with any user guide should be to help your reader decide if they’re in the right place or whether they need to keep looking. A clear and specific statement removes any doubts and sets the reader’s expectations.

3. Write for the appropriate knowledge level

I still come across documentation aimed at business users that explains how to navigate between different pages in a web app. While this might be appropriate for some audiences and products, many of the examples I’ve seen can do without it. If your target audience probably uses software every day, don’t patronise them by explaining how to click a link to open another page in the UI.

4. Structure is everything

How you structure your user guide will make a huge difference to how easy it is for a user to follow it. Particularly with more complex products, there might be quite a lot of information that the user needs to take in before they can get the most out of your software. This is where building up knowledge in layers comes in handy. Rather than trying to cover every detail on the first page, break it down into digestible chunks. Your aim is to give the user a framework or “mental model” for understanding your software, so start with the simple and build up from there.

5. Use headings to break down the material

Research into reading patterns online confirms what many of us already suspected – people are far more likely to scan when reading content on a website. Given that most technical documentation is published online, this is worth knowing. Breaking your user guide down with appropriate headings makes the content easier to skim-read and helps the user skip to the parts that are relevant to them.

6. Only include the information the user needs to do the job

If you’ve been involved in the product development process or you’ve been asked to create a user guide with the help of internal wiki content, it can be tempting to include lengthy explanations about how your product works under the hood. However, unless the reader needs this information to complete the task at hand, leave it out. Yes, these details are critical to those on the inside, but very often users don’t need to see inside the sausage factory.

Having said that, there are times when a longer explanation of inner workings might be of interest to some of your users. In this case, consider having a separate article or section that you direct readers towards if they want to know more.

7. Distinguish the optional from the essential

If there are things the user can do to make their lives easier or get a better result, do include them. Don’t be so keen to exclude extraneous information that you cut out useful advice. However, make it clear when something is a tip – something the user may find helpful in some contexts – or just the way the product should be used.  

8. Make sure your content is accurate

An inaccurate user guide is far worse than no user guide. Readers place a lot of trust in the official documentation for your product. Think of it from their perspective: if the creators of the software can’t get it right, then who can? Publishing content that is wrong or misleading can do anything from frustrating your users (and potentially costing you in reviews, referrals and renewals) to landing you in legal hot water. Ask subject matter experts – such as developers, QA staff or product managers – to review the draft and make sure your keep it up-to-date once published.

9. Images can communicate a thousand words

Depending on the product, screenshots, diagrams, and videos can make your content more engaging and easier for readers to understand. Just remember that there are several reasons why someone might not be able to view an image – from visual impairment to bandwidth issues. Ensuring the same information is also covered in the text can help with this.

10.   Write in plain English

If writing user documentation is outside of your comfort zone, it can be tempting to dress up a user guide with fancy jargon and flowery prose. There’s really no need. Remember that you’re writing to inform; your aim is to help the reader achieve their goal. Filling a user guide with unexplained acronyms or crafting sentences so convoluted the reader has to perform mental gymnastics to understand your point will not help them. Instead, you want to keep it simple. I know that’s often easier said than done, but there’s so much to say that it’s a topic for another post!

And what of my freelance “colleague”? A few days after our conversation, he came back to tell me that they had not only restructured the guide to focus on user goals, but that the ensuing discussion had made them realise the benefits of tackling documentation earlier in the development process. Music to my ears 😊