A user guide for user guides

You did what today? Wrote a user guide

A confusing title for a confusing concept. Today I wrote (part of) a user guide for one of the deliverables we were handing over to a client. We had completed a part of the project and now needed to document how a tool – which we had built – worked, so the client could use it in the future.

I’ve written a few user guides during my time in management consulting. A common theme on technology engagements, user guides are often completed near the end of the project as a final, summarising document the client can use to remember how their shiny new tool works. When I had my first experience of writing a user guide, there were, ironically, no instructions for me to follow. Past examples, peer-learning and of course, Google, got me through the initial trial-by-fire.

How to write a user guide

There are blogs and websites that all have tried and tested methods for how to write user guides, manuals, instructions and technical documentation. I’m going to list a few of my top tips for writing user guides specifically for management consultants.

Caveat everything

OK maybe not everything, but almost everything. It’s important to make sure everyone has the same expectations of what the tool can do. There’s nothing worse than uncovering a deep misunderstanding due to ambiguity in the scope of a project, language barriers or something being vague in the user guide. Strike one of these off the list by making sure your guide is water tight and calls out all the limitations and exceptions the tool or product you’ve delivered may have.

Reference clearly

Something many people learn about at school or university is how horrendous a task it is to accurately cross-reference other parts of a document. Microsoft Word doesn’t do anyone any favours, but you’re likely to be confined to Word or PowerPoint when writing your guide. Take great care to manually check the document for references to sections, figures and external sources. It’s elementary really but not worth getting wrong as one mis-referenced heading can undermine the credibility of the entire document.

Repetition is fine

Seriously, repetition is fine. I recently had a heated discussion with a colleague about which section something should appear in. I the end, my opinion was that the information in question should feature in both sections. I do not believe this is confusing, especially if different people are likely to use different sections of the user guide independently. If you really don’t want to repeat yourself though, see point two and make sure you’ve got a good referencing system in place.

Structure = understanding

Not a revelation, this one, but I’ve seen it overlooked before. Be prepared to re-work your document many times over before you hit on the structure that you think will land best with the client. Ask yourself questions like, “How much pre-amble does the client want?” and “Should we order things alphabetically or chronologically?” Generally the order of sections should follow the order a process is carried out when using the tool in question. However, when there are multiple processes this can become a less-than-straightforward consideration. Finally, never omit the contents and glossary pages!

Use appropriate language

Just because you’re writing a professional user guide for a huge multinational client does not mean you need it to read like top-tier technical documentation. There will certainly be situations where this is a requirement, but give it some thought first before deciding. Sometimes a more down-to-earth tone can drastically improve the user’s comprehension of information. I would even recommend combining formal and informal tones, especially if you are catering to multiple audiences. However, this must never compromise consistency.

That concludes my short user guide on user guides. Let me know if you think I’ve got it all wrong or if you have more tips on writing effective user guides. I will try to link some examples of interesting or different user guides in the comments below if I find any.

Leave a Reply

Your email address will not be published.