Reading The Fine Manual

I’m always amazed how long people spend trying to figure out software by fumbling around with it, rather than reading the manual. Now, I know what you’re thinking. You’re thinking “Golly Martin, reading manuals is all swell and good, but I’ve got to write code and fix bugs. If I spend an hour or two reading those manuals, well jeepers, by the end of it I won’t have written a single line of code, or fixed a single bug. Not one line! I don’t have time to read them, I need to get things done!”

So here’s the thing: you should only spend two hours on something boring (like reading manuals) if it will save you more than two hours over the course of your life. And usually, you spend a lot more in the trial-and-error — commonly called floundering — than the two hours it would take to read the manual. Not the whole manual of course, and I don’t mean to memorize the parts you do read. But for three different people in three different jobs, I’ve had to point them to the first two chapters of the Subversion manual, titled “Fundamental Concepts” and “Basic Usage.” Despite the fact that they have “fundamental” and “basic” in their names, people seem to think it’s ok to not know this stuff. Until they get some <<<<<<<<<< in their source code, and they don't know where it comes from, and subversion won't let them check in their code. And then they spend a couple hours trying various things to figure it out, and nothing works, and they have to read the manual anyway. I've also seen someone spend hours trying to lay out an image in Word to conform to a conference's layout guidelines, and several people trying to get resizing working in Swing without understanding Swing’s layout managers. Note: I was one of those people.

So, if you think you can learn a tool’s mindset — the kind of hammer it is and therefore what sort of nails it thinks everything is — by trying things without understanding, you should. But typing random svn commands, or calling random layout-related functions when building a UI, or is like playing Battleship or Mastermind: you only get a few bits of information on each attempt, and the information you get is more like clues in a puzzle than a clear explanation of what you need to know. Please pay attention to the time you spend in trial and error. Because if it’s more than the time it takes to read the manual, you’re actually getting less done than you could. And it’s easy to notice this time: it’s generally frustrating, unproductive, quality-of-life sucking time.

If you find you’re working that way, please don’t feel bad. Most people do it. I’m not sure where it comes from. Bad, “results oriented” managers? Most people learn it before the first job. Bad managers depicted in movies and TV? Parents? Teachers? I don’t know.

But if you really want to spend the most time on the fun part of your craft — creating stuff, not debugging it or pounding your head against the wall — then you need to invest in yourself. It’s in your best interest. And it’s in the best interest of your company.

This entry was posted in Brain Rental, Process. Bookmark the permalink.

5 Responses to Reading The Fine Manual

  1. Great post Martin.

    This seems to be a particular instance of a more general phenomenon: people seem to prefer a “fuzzy” future cost to an definite immediate cost, even if the future cost could be significantly higher.

    See: unit testing and credit cards.


  2. martin says:

    True, and its well documented in psychology and economics. Good point.

  3. Mike says:

    I think it derives from the fact that a large part of the education system encourages people to “figure out a problem” rather than to look up an answer. Starting from elementary school (if not before), students are taught that they’ll “learn more” if they figure out how to solve something themselves instead of looking for the solution. This mentality carries over into situations like the above. It’s not just that they necessarily feel trial-and-error will be quicker, but that they’ll learn more about the product / process in question by learning instead of looking up. It quickly becomes almost unnatural to ever look something up without first trying to solve it on your own.

  4. martin says:

    Good point Mike, I agree.

  5. Because I do a lot of tech support and customer service as part of my job, I see a ton of evidence that people do not RTFM. Our old documentation comprehensive but overwhelming, so we’ve shortened our help materials sent on sign-up for our site to a mere 20 lines. About 4 lines down, right below user name and password, is the answer to our *still* most commonly asked question, ie, “what is my unique url?” ::headdesk::

    And one thing I’ve found beyond the tendency for people not to ready anything you send them is that often those that do aren’t the type of learners that grok what they read. We had a customer who insisted I call her at work to explain how to do something. It didn’t click when she read it on paper, but as soon as I read the same identical text over the phone, she got it. So part of our challenge is to provide materials for different learning styles. We’re currently working on a video FAQ for simple tasks on our site. Of course, we’ll probably still have to point people to these materials instead of them looking for them, but hopefully different forms of the information will make a difference. It’s my firm belief that if manuals, in general, were better written and organized, more people would read them and end this vicious cycle.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s