RTFM – Read The (Fine) Manual – A rant on documentation

Look at any product you buy, and chances are it will come with some kind of manual. Maybe it’s a one page quick reference guide. Maybe it’s a DVD instructional video. Maybe it’s a giant tome that cost some poor section of forest its life. The point being, that product came with documentation that tells you how to get the most out of the thing you just bought.

Example of documentation
Image from Flickr
Companies don’t create this documentation out of boredom. It costs money to have a technical writer on staff. It takes time and money to print and bind a book, or setup a studio and shoot an instructional video. If the company could cut those costs and apply the savings to the bottom line, it would. So, why would they go through this effort?

Why write documentation?

As someone involved in a small business, I’m close to the products we produce and sell. Swimming around in my head is a sea of one-off customizations, tweaks, or first-time creations. Many of those machines had to have some additional documentation and training for the customers. As the guy who writes the manuals, let me say, it’s not necessarily a fun process.

Imagine you’re Iron Chef Bobby Flay. You’re going to teach someone how to make a simple hamburger and french fries from scratch. You have so many years of experience in the kitchen that you’ve forgotten more than most people ever learn. You don’t have to think about firing up the grinder attachment on the stand mixer to grind your beef. Need some tomato slices? Whip out the mandoline slicer, or just pull out the trusty chef’s knife and slice one up in 10 seconds or less. But, you’re not making the dish. You’re teaching someone else how to do it. You have to stop and think about every little step you take, what could go wrong, and make sure it’s perfectly clear to the student what they need to do.

The same thing happens when writing a manual for a product. You have to selectively forget everything you know and approach the device with fresh new eyes. You have to write down every key press, setting change, machine movement, AND you should explain WHY you’re pressing that button, changing that setting, and moving that piece. It’s a slow, tedious, time-consuming, mind-draining process. Then, to make sure you haven’t missed anything, you need to bring someone in to check your work. This testing and revision process can go on for quite a while.

All of this, in the (sometimes futile) hope that the end-user will consume the documentation you have provided and get the most out of the product you’ve built. When they do, it’s great. When they don’t, you get the phone call asking “Why isn’t this working?” and what’s one of the first questions that gets asked in response? “Did you read the manual?” Why do we have to ask that question? Because often, the answer is right there in the documentation that was provided.

To conclude my semi-rant, I’ll admit nothing is perfect. We’ve had revisions to manuals because of a missing step or some seemingly innocuous typo. But, for the most part, the manual is a key part of the product. So give it the respect it deserves and read it.