It's all there in the manual! Is there a way to write a User Guide that will not end up in the bin?

Oh, got to love those customer facing documents, don’t you? By the time legal, marketing, regulatory and the rest of the team are done reviewing those, it almost sounds like Muppets show’s Statler and Waldorf wrote it. (if you don’t know who they are, just watch this short clip: https://www.youtube.com/watch?v=ZyZNQumtPEw) 

Every time I need to deep dive into editing one of those, I struggle to find a way to make sure it’s not going straight to the bottom drawer, or worse, to the trash.

You can often see manuals which contain too much information. It will enable you to answer most questions with “but it’s in the manual!” and will result in an unhappy customer.

So is there any way to make a user manual that can actually be read? That is helpful? Not too cumbersome to work with? And at the same time contains the information your user really needs?

The short answer: Probably not. But there are some things you can do to get close to it.

I am not going to dwell here about the techniques, neither the outlining, nor the style or anything like this. If you do wish to read some more about this, better look at this: https://www.prismnet.com/~hcexres/textbook/user_guides.html

What I do want to talk about are the few questions you must ask yourself before going to write such a document.

• Shall I include everything the user would need in my manual?

My product is very complex, there may be many adjustments a user may need to do.  Do I have to have them all in my manual?

Answer:

NO, NO, and again – NO!

It’s trivial I know, but I’m looking at my office now and I can see at least 4 different manuals that are more than 200 pages. I never looked and will never look at them, actually – no one will.

You have to limit the content and have very clear guidelines to help the reader browse through it.  The 80/20 rule applies here as well: choose 20% of the workflows that 80% of your users will use.

On top of this, have a clear Table of Contents or other browsing method, that by using some keywords can get them exactly to what they need. 

• So, if not everything is in the manual what needs to be included?

Which workflows \ problems should I cover? The frequent ones? The more complex? Those that break a lot?

Answer:

That’s always the difficult part, OK - the 20/80 rule can be applied– but what 20% to use?

In my opinion, always go with common, simple workflows.

Most of the users will use the system the way it was designed, the routine simple tasks. Those tasks must be well explained and  well documented.

Some advanced users may use the system to its limits, you may want to have those workflows covered as well but my observations show that most of those advanced users tend to ignore the manual anyway, they will figure it out by themselves.

Also it is very important to cover your system’s weak points. If your system needs to be operated in a specific workflow, and any alterations or deviations will make it do something wrong – make sure it is “in the manual” (even for legal reasons).

Last but not least, Safety, regulation, and basic troubleshooting items needs to be included as well (obviously). But also those can be written in a way that is easily browsed. A good example of a troubleshooting table includes the below fields:

-         Topic.

-         Keywords

-         Part of the system that is affected.

-         Issue observed by the user (also with keywords)

-         Possible root cause\s

-         Solution.

     If all of those fields can be filtered and searched through, your user will find it easily.

•  What do I do with everything that is left out?

OK, so my customer got into those “one in a million” cases (that are not in the book), what shall they do now?

Answer:

To start with, you still need to have written instructions to all the workflows and troubleshooting items. It can be derived even from your verification process. If someone calls your agents with an issue, they need to be aware of the solution.

So you have it written, but not in the manual. What can you do with it? Luckily for us this is 2018, everyone got internet today!

A good user manual will have references for “need more data” sections online. A great user manual will have troubleshooting and workflow links embedded into it, that will refer the user to the exact web location he needs to get the answer.

A great example by Apple is the online troubleshooting table: the user manual refers you to a link and as you type keywords into the description field, suggestions and possible solutions pop up.

The printed manuals can have those sections referred to with links, and if it’s a must (for systems working where there is no Wi-Fi) have those items at appendix printed in a separate notebook in the manual!

•  Shall I cover operations for different levels of permissions at the same document? Or shall I create 2 different manuals: one for users and one for admins?

As there are few levels of permissions and operations possible in my system, what information needs to be exposed and to whom?

Answer:

Don’t mix, too risky. I think we can all agree on that. You need to have 2 notebooks: “User Manual” and “Administrator’s User Manual”.

When deciding on this, there is an immediate question that comes to mind, shall I duplicate the content of the User Manual to the Administrator’s one and add on top of it? Or should I keep it with no redundancies? (Administrator’s manual will be on top of, and different from, the regular manual).

There is no clear cut, both options work. I prefer the later to avoid the 200 pages notebooks, but administrators are used to this. I usually ask myself if the administrator has totally different workflows he needs, and then I separate with no redundancies. In cases the administrator has similar workflows with additional options, I may duplicate the manual and add the additional data.  

• Last but not least, who should review the manual before it is going to the 1st customer?

Answer:

Easy, everyone!

OK, jokes aside, I do mean everyone. There are some musts: regulations, legal, the service team plus the usual suspects. But anyone who is ready to spend some time can have an interesting new view that can be beneficial. Marketing can help with design and logos, developers may have some points for troubleshooting suggestions you might have missed, while people that were not part of the development process can comment about what they understand (best prediction to what your customer will understand).

Who can edit \ enforce changes to your manual? As few as possible. If marketing says “you must have this because this is what our PR claims”, and developers ask to mention “wrong workflows” that lead to a defect not yet fixed. Adding the legal and regulatory comments, you will have a document that just doesn’t “flow” and is not readable. Your stakeholders should be listened too, and there are some things which are mandatory. But don’t be afraid to say “this doesn’t belong in here” about anything. Keep in mind that this is the only written thing left behind and too much information is not always good …

Bottom line, more often than not your user manual will decorate some shelf, be a computer monitor stand, or be thrown into a drawer somewhere. We need to face the fact that today no one bothers reading those. But when needed, a good manual can be the difference between having a call center that handles tedious calls 24*7 to having 3 or 4 talented service engineers that solve real problems.

What will you rather manage?