How To Write Great User Guides

Most programmers dread documentation. The thought of having to write anything but code makes them tremble (myself included). The reason is because it’s not what we’re good at, our job is to program, not to write docs for that code.

But what happens when our boss comes to us and asks us to write a user guide for our latest application? Below I’ll go into detail on writing great user guides.

Put Yourself in the Users Shoes

One thing that I always try do when I have to write any user guides is I put myself in the users shoes. This allows me to see their mindset and I start thinking about what they want to get from the document. This isn’t always easy to do, especially if you’ve written most of the software yourself, but if you can think like a user, you’re user guide will turn out great.

Get a Couple Users to go Through the Document

Once you’ve written the user guide, have a couple of your potential users go through the document. Once they’ve read it, ask them what parts they found confusing, what parts weren’t written properly and what parts gave them troubles.

This will allow you to modify the guide and make it more “user friendly”. The end product will be more informative because real users helped make it.

Keep Out as Much Technical Aspects as possible

This document is a user guide, not a technical document. Try to keep as much of the technical aspects of the software out as possible. Does a user really need to know the underlying technology to use the system? The answer is of course, no, so try to keep it out of the user guide.

If you can keep the user guide limited only to things that the user will need to know to use the software, it will keep the guide as short as possible. This will also help with the clarity of the guide, keeping it easier to read.

Use Pictures

I know this sounds a little juvenile, but use pictures as much as possible. They always say “a picture is worth 1000 words” and it’s true in this case. Using pictures in the user guide is a great way to keep the user interested and at the same time show them how to use the software.

If you had a 100 page user guide without any pictures, most users would get bored before they got to the half-way point. Using pictures is more efficient so the guide will be shorter and the pictures will keep the user interested (which is the point).

Good User Guides are Important

Writing good documentation is important because it’s sometimes the only way your user will learn the software. If you have clear, well laid out user guides it will make the learning process easier and faster and will make the user happy.