In November 2004, Peter Vogel wrote this really good editorial on User Manuals. Have a successful 2016 everyone.
So, I have a cat. At night, when I get in bed, the cat, desperate for love/attention/pets, throws his whole body against me. But that’s not enough—he then slides up along my body and mushes his face into my face while purring like a washing machine with a bad set of cogs.
It’s not nearly as attractive as you might think.
If I don’t respond because I’m too tired and want to go to sleep, the cat performs this act again. And again. And again. Eventually I punt the cat. A definition of insanity is “Doing the same thing over and over again while expecting to get a different result.” This is also, apparently, the definition of having a brain the size of an apricot.
So, I have a client. My client desperately wants to reduce help desk calls. I was in, supposedly, to “tweak” the user interface. But it was too late for the UI: Any significant change to the UI was going to require a major rewrite (definition of fine-tuning: “The belief that small, insignificant changes will result in something other than small, insignificant improvements”).
However, there’s an alternative way of helping bewildered users: user manuals (“Doctors bury their mistakes; architects cover them with ivy; user interface designers write user manuals”). “No,” my client said, “that’s not the problem—we have great user manuals.” He then pulled this whacking big book off a shelf and handed it to me (and I do mean whacking; you could whack anything into submission with this tome). Hefting this brick (roughly the size of both volumes of the Access Developer’s Guide), I asked if this manual covered all of their applications. But, no, it turned out that this was just the manual for the application that I was supposed to review. The problem, I was told, was that the inconsiderate users wouldn’t read the manual. Most of the questions that the help desk was getting could be answered by reading the appropriate section of the manual over the phone to the caller.
To this day, I don’t think he understands why no one wants to read this book or take it with them on the road. Many airlines would classify this book as a separate piece of luggage. In a moral world this book would have had wheels and a handle to pull it.
“My,” I said, “what a big book you have. That must take a long time to produce.”
“Yes,” he said, “it covers everything that the system does. But we’ve found ways to reduce the labor. The whole section on how to start your computer, work with files, insert floppy disks, and all of those basic tasks is set up so that we can automatically insert it into all of our manuals. Some of the other sections that are used in all of the manuals are set up so that we can tailor them to the individual application.”
Okay, let’s stop and think about this: My client knew that no one was using their manuals yet they still kept churning them out. Furthermore, they concentrated on finding more efficient ways to produce these manuals that no one used. This is insane: “Doing the same thing over and over again while expecting to get a different result.”
They also had a similar process in place for project documentation. Every project produced an enormous pile of paper describing every part of the system. I can’t imagine under what circumstances anyone would use any of this information. For one thing, how would you know if the information in that documentation was both complete and completely accurate (even if it was, how would you know that)? If a programmer implemented something based on the documentation and it didn’t work, would anyone accept as an explanation “Well, the documentation said that it would work”? You always have to look at the actual code, not just review the description.
Fortunately for us, with Access and the wonderful tools from FMS and other vendors, the documentation problem doesn’t exist. We can generate as much or as little system description as we need, and that material is guaranteed to accurately describe the current version of the system. This leaves us free to document what’s actually useful to developers: Why the system is written the way it is.
I couldn’t do anything about my client’s documentation process (they weren’t using Access), but I’ve seen the user manual problem far too often. And I’ve seen users abandoned to their own devices far too often.