Aaargh! Why is documentation so often so bad? Fifteen year, fifteen years SIGCHI has existed, born out of a clear need for better software, in a time when everything in the software world started changing, when software all of a sudden started acting like it was people who used it. There was a time when you could be using a program and not know how to achieve what you wanted. There were no menus or buttons to give you clues, so you had to remember it all, or read the documentation. It seems like we have largely won the battle for software. There is still much to be done, but companies seem to understand that the interface of software needs to be thought about. How come we still haven't learnt the lessons of software when applied to its documentation?
I'm sorry. I've just had a bad week. I've had to install three pieces of hardware and software. The first was on a recommendation from someone. In my apparently never-ending search for good email software, I installed a package that claimed you could read news and email in a uniform way. In minutes I was reading news, no problem, I hardly had to even look at the documentation. But mail was a different matter. I went to the documentation. It talked about reading mail. It talked about virtual servers. It talked about setting variables for the virtual servers. But it didn't tell you how to do it!I tell you, I spent a whole day trying to get that package running before giving it up, and going on to other things.
One of those other things was installing a piece of hardware. At the beginning of the 80's a colleague of mine wrote a joke film script of someone arriving home happily carrying a newly bought personal computer. There were two boxes, a big one, and a little one. On opening the boxes, it turns out that the little one is the computer, and the big one is the documentation marked READ THIS FIRST. The once happy owner now bursts into tears. Well, that was me this week. I had to install a handy little box, a piece of hardware with such pleasant specifications that you'd almost want to weep with joy since they seemed to have thought of everything. However, the documentation is several times larger, and many times heavier than the little device it is describing, and after trying to work out how to install it, it wasn't with joy that I was weeping. The box has one green light on the front to show it is switched on, and which blinks if the device hasn't been installed properly, and that light blinked at me all day, but I couldn't work out what I had to do to get it working. In desperation I went to the Web and typed in the name of the device. Luckily I found a page written by someone who had installed one of these devices. It was two sides of paper. It was all I needed...
The documentation reminded me of some documentation I had read of a package, to see if I wanted to use it. It started off with a list of features. The list started:
- It's small
- Very easy to install
- Simple to maintain and configure because all you need is one
executable and one configuration file
- Is event driven
- Does not use any temporary files
- Uses standard egrep regular expressions
- It poses a very low impact on your system's resources
etc. etc. etc.
But the funny thing is, it forgot to say what the package actually did! You could tell from its name that it had something to do with mail, but somehow they they didn't think it was important for you to know its actual purpose.
Finally, I recently bought a back-up tape unit for my computer at home. The documentation was mercifully small, and they had obviously wanted to make the documentation seem easy because it was full of little cartoon characters of smiling computers telling me that they were friendly, and on telling me to switch off my computer, telling me what the switch would look like (like I'd never switched my computer off before or anything). The documentation told me how to install the hardware and software, and how to back my files up, and how to restore individual files, but I was amazed to find that nowhere do they actually tell you what to do if your hard disk crashes, which is the real reason I bought it. Personally I'm worried that the backup software keeps essential information on the hard disk which it uses when restoring files, which would mean that if my hard disk is unreadable then so are my backups. Unfortunately I can't tell from the documentation if this really is the case.
Documentation is like software: it has a user interface, and since people tend not to read it serially, it is sort-of interactive as well. The user has requirements and tasks to achieve, which you can analyse and treat in the documentation. It's not hard.
© Copyright Steven Pemberton, Amsterdam, 1997. All rights reserved.
First published in the SIGCHI Bulletin, October 1997