User Guides

old_fart_mode = on

They don’t do user guides as they did before… When I was young the manuals were clear, easy to understand and really, really helpful. Not how they are today…

STOP!

old_fart_mode = off

Stop, old fart, You don’t know what You are babbling about!

What f*ng user guides?!

Exactly.

There is no point complaining about a quality of something what doesn’t exist anymore.

What is a user guide?

For anyone who is older than, let’s say thirty this looks like utterly stupid question. But for Younger generation I think it is important to explain what the user guide is. Or rather what it was.

I suppose when You are reading it You start thinking that I am an utter idiot. Sure, I am. But before You leave just think: have You seen a full blow user manual for any commercial software You used during last, let’s say ten years? Fifteen? Twenty? Well… maybe twenty years ago You might have seen it.

So what the hell is a user guide?

First step: User guide is a book.

It may be on paper or it may be in an electronic form. It doesn’t matter. What matters it is that it is a book and it is obliged to behave as a book. This means it must be easy to read, must use clear language. Must be easy to understand.

Every requirement of good novel must be met, except, maybe, the flexibility of the language. Story must flow, the gun must be hung on the wall before it fires. And anything like that.

All right, so once You know what user guide was now it is a time  to ask Yourself: What it was used for?

What is user guide used for?

For a carpenter hammer is to hammering a nail. For a nail a hammer is something used to be beaten in a head. This means that the answer to above question will strongly depend on from whose point of view we are looking at the problem.

Whom is user guide for?

This is very important to understand, that user guide is for…. well…. the user. When You write a user guide for Your company software remember this is not a book written for an internal use. There is no “everyone knows what  <enter any important program function here> is”.

A user guide is for a user. Or, what is even more important, for a future user. And future user has one very important property: they do not know anything about Your program. There may be obvious for You that RHINO is…. hell if I know what it is…. but for anyone else it will be a damn big animal what loves bathing in the mud.

User guide tells user what this software is useful for.

This may again sound stupid, but many manual writers do forget about it. Try for an example a manual for mockito Java library. Starting from the first sentence the are telling You how to mock, how to make a mock, hot to use a mock, and how much mocking will help You. I had lost about three hours, which included looking into its source code to understand what the hell is “mock” anyway.

This kind of user manual is a pure form “customer repellent”. If Your future user can’t understand after reading a page or two what is this software for, then how can You expect them to buy it? One working hour costs about, let’s say 30Euro. Do You honestly expect Your future client to spend 50Euros to understand that this software is not for him? Sure it may be worth for a selection of 5’000Euro software, but for anything around a thousand it is naive.

Remember, Your future user must select Your software from tens of available solutions!

Ok., so Your user read an “Introduction” chapter and now understands that this software may be for him. What is the user guide used then?

User guide allows to avoid costly trial-and-error usability validation

This day I tried to install on a smartphone something what will allow me to record the phone call. This kind of activity is fully legal for a private person in my country. My old Nokia phone has this function. This new smartphone advertises on the Samsung support page that it has it, but this function may be not available in some countries.

Notice the underlined may be and some.

So does this smartphone have it or does it not?

The only way, according to Samsung, to gain this knowledge is to spend 500Euros to buy this phone, check it, return and hope for a refund… Nice, isn’t it?

So I tried a google phone app. Again You may find on support page, that to get this function You must have Android 9+ and newest version of the application. Fine, no problem…. except that after spending a lot of time on downloading it, after allowing it to crawl all the data on a phone it appeared that this function is not there anymore.

If both the smartphone and a phone app would have a well made user guide I would know it from a scratch and stay with my Nokia phone.

The good user guide allows Your future user to decide, if Your product fits exactly his/her needs. Not just may in some countries but it f*ng do!

User guide explains how to do things…

So what I would be looking for in that above mentioned non-existing user guide?

I am a very, very accurate person, so I would have skipped the “Futures” chapter and  look for a chapter called “Recording phone call”. I would look into it and check how to do it. I would possibly find there some information where the recording is stored and in what format. If there are any limitations there is also probable that they would be explained there…

….in every f*ing detail!

And I mean it. With screenshots, colors and etc. That damn button does it when You touch it. That empty space, when You touch and hold it will do something else. And if You try to wipe left to right that mugshot on the top the phone-book entry will appear.

User guide save user spending hours on “discovering functions”

“Discoverability” of a user interface is a myth which stands behind the idea of “flat user interface”. Flat equals to: active and inactive elements do not differ.

If You read this blog, which is using a ready-made template without me being able to tune it, You will notice at the top gray “Main“, “Blog” and “About“. Below You will find equally grey “software quality and concepts“.

Do they differ visually?

Not much. At least not for me. They are all gray text, are the not?

Except, that three first are active and the last is not.

Gladly the designer of this template was not an utter idiot and made those elements to react on mouse hoover over it. So if You will try to move mouse around every damn object on a page You will probably find what is active and what is not.

I let myself to underline try to move because unless You will try to do something You won’t even know that there is such a possibility hidden up there.

Sadly not every one is so smart as this author was.

Never less did You try to hoover Your finger over something on the smartphone? It never works for me.

And what if “flat” is moved to an extremity, as at deviantart.com page where an empty space reacts on mouse click? Obviously with this style of design to be able “discover” all functions You will have to end up left clicking, right clicking, dragging, tapping, nipping, wiping and pushing every damn inch of the screen to make sure that You did not miss anything important. And remember, on PC You also hava a 100+ keys on keyboard which can be pressed in (100^100)^10 combinations cause You have ten fingers.

I am not against “flat” design. If fashionable look is very, very….very^infinity important then it is a must. I have nothing against top left empty corner to react on mouse click when there is some text selected providing I can read about it without spending hours on searching over the net.

“Discoverability” is a madness and a good user guide may save countless tens of hours of work and frustration.

And, apparently, save a life of a smartphone which may not survive to be thrown out of the window from fifth floor.

Three kinds of users

There is one more thing to remember about a “user” the manual is for. That there are three of them, which do stand in order of appearance:

1. Future user, who needs to know if this product will met they needs.
2. First time user, who will learn, step by step, how to use the program in most efficient and proper way.
3. Returning user, who used program some time ago, but just this damn damp day is too hot for him/her to remember how it was done and where this damn button is hidden.

The all need Your manual, but they need it for an another reason and will use it in a different way.

Summary

In this blog entry You might have read some obvious things. For some of You it was so obvious and boring, that You just clicked away. But for some of You it might be an eye-opener into a land of a software which is not only nice looking, but also easy to find, easy to learn and easy to use.

In next blog entry I will try to switch a side and explain why there are no user guides anymore and why You, a software company owner (or in fact: any company owner) should do absolutely everything to prevent Your employees from creating such an evil thing like a “user guide”.