Aaron Brethorst

Round peg in a square hole, rabid generalist.

Why Must Users RTFM?

| Comments

Kathy Sierra, co-creator of the O’Reilly Head First book series (including the super-cool Head First Design Patterns book), has a very long, very passionate post on some of the fundamental disconnects product creators have with their documentation.

Kathy nails the fundamental issue right on its head:

[Your average manual] suffers from one huge mother-of-an-assumption: that the user knows exactly what to look up!

…and goes on from there. Kathy’s absolutely right: 99% of the time, I have no idea what the capabilities of a new product are, but I have a pretty good idea of what I want to accomplish. I might not have the slightest clue that Javascript has first-class functions. Even if I did know this, would I understand how this benefits me in a practical way? The best way to teach a lot of this stuff to a user is by presenting them with tasks, or a cookbook of sorts. “I want to…” tends to be a much better way of structuring content for a user than throwing them into the thick of

public class Foo : Object

Of course, the inductive model does have its limits, and a manual structured in this fashion can never take the place of something like K&R or the Wizard Book, but it certainly has its place.