September 14, 2005

In her last comment, Kaylene asked me if I ever get discouraged about the whole "no one reads documentation anyway!" issue. I typed out this long response, then decided it needed its own separate entry.


The joke around here is that no one reads the manuals unless they're bored while on hold with phone support :-) I don't really get discouraged about this issue because the products I write about are interesting enough to motivate me personally, and because whether or not anyone reads what I write, I know it's there in case a customer needs it.

In the case of some more complicated features I'm currently writing, I've had developers come up to me and say "I didn't understand what this feature was about or how it worked, but I read your user manual chapter, and now I get it." So there's some small comfort for me in that aspect :-)

Funny story, tying the iPod and tech writing together: this past weekend I bought a slightly-used iPod mini from a guy on craigslist. He advertised it as being in the original packaging, and lo and behold, the user manual was completely sealed in its original plastic. I joked with him, "it's guys like you us tech writers hate!" But I know it's just because the thing is so easy to use that detailed documentation is unnecessary. The menu items and such on the iPod are so self-explanatory that Apple could probably get away without shipping an iPod manual; but that looks unprofessional from a marketing/brand standpoint, so I doubt that'll ever happen. At my last job, I spent a couple months overhauling the manual and packaging the user received with their computer. We tried hard to make a lasting impact with a "professional" presentation, even though the information inside is as simple as "Plug the blue monitor cable into the blue video port on the back of the computer."

I do read user manuals and instructions sometimes; it just depends on the product. For instance, I had to read my coffee maker's user manual to find out how to brew at a specific time in the morning. Does that suggest an unintuitive user interface? Probably; I never would have figured the steps out on my own by just looking at the buttons on the front. So the issue might be, is the user aware that they don't know everything about the product? Is their personality type the kind to admit they aren't smart enough to figure out which functions do what and which buttons go where? I suppose these more "modest" types of people might be more inclined to leaf through the user manual (or page through the online help).

I recently bought Jade Empire for the Xbox and looked through the user manual while waiting through the incredibly long loading screens. The combat system in the game is confusing at first, and though the manual didn't provide all the information I need (I'm a "big picture" person, a viewpoint which seems to be rarely presented in the documentation I come across), it helped me understand what I was seeing onscreen so that I could figure the system out after a little while.

However, for something like a computer part (optical drive, video card, etc) I definitely don't read the manual. That's only because I've been installing computer parts for several years and don't need a manual to tell me what I already know :-) And I have not broken the seal on the iPod's documentation; I doubt I ever will :-)

It's interesting documenting a programming language though, because our end users are using our products to make other products. So we're really the middleman. A large part of our documentation comes in the form of function reference: we detail the purpose of each function as well as the relevant arguments and data types. Coming from a CS background, I know this information is extremely helpful, especially because the majority of the programming done out there is not original design, but simply maintaining and updating existing software. In these situations, function reference is invaluable, and I would hope that no one would call tech support just to figure out how a particular parameter affects the function. Then again, you never know :-)

Another reason I don't get discouraged is because I know there are some people out there who do read the documentation. I know this because we get comments on the documentation when people get stuck trying to work something out. Of course the comments are usually about incorrect or unclear information, but that's just because the motivation to say "Good documentation, guys!" is not as strong as the motivation so say "Hey, this documentation sucks!"

However, I don't expect someone to sit down and read the user manual cover to cover. Especially not an online user manual. This expectation factors hugely into the way I organize and design the help system for the Control & Sim products. For example, we rely a lot upon the "Search" and "Index" features of HTMLHelp. If we don't organize and test these systems properly, we're reducing the usability of the help system. We do a lot of internal testing, and we sometimes test actual users, but we can always do more in that respect. The fact that we're expected to participate and drive this organization and testing is just one reason I enjoy working here :-)

1 comment:

  1. :) Wow, I feel like a celebrity...

    Our documentation is very similiar in function (no pun intended). I am most often involved with writing service and parts manuals. They are used by the technicians that service our kitchen equipment, while they are servicing them. They are organized with this in mind. The first half of each SP manual contains a multitude of step-by-step lists for various service procedures, troubleshooting, phone numbers. They are organized in a logical order from the smallest, most routine procedure to the largest, most rarely done procedure. Each includes a table of contents that is broken down so that each list can be found quickly and without a lot of searching. Headings are large and bold to make visual scanning easier. They are made of a durable paper similar to cardstock, but stronger (to survive being tossed into cars, getting oil spilled onto them, etc.). The second half of the SP is an extensive parts list, and by extensive I mean at least 20 pages. This section contains full illustrations and part names/numbers so that should a new part be needed the technician can call us and order it. This section is also heavily used by the men in our call center because they get many calls from people with no idea of what they need.

    We don't expect people to read our manuals cover-to-cover, either. However, because of the nature of kitchen environments and computer literacy issues within the technician-fields, we do not provide HTML help (though I would like to do so). Just to clarify, I am not implying that technicians can't learn to use computers, they just don't usually have any interest in doing so. They'd rather be hunting/fishing/footballing, in my personal experience. So, instead, we provide .PDF versions of our manuals ready for printing.

    I know some technicians that never read a manual. They "know" how to fix the fryer. The problem with this is...two-thirds of the time, they don't. :)

    Neither of us writes for the average consumer. But when I buy a product...I always read the manual. Regardless of whether I know how to use it or not. I find them extremely interesting. Call it a quirk. :)

    I hope Austin doesn't get blown away by Rita. Evacuate if they tell you to do so. Have a great day!