Two more reasons why so many tech docs suck

A great deal of non-reference technical docs suck for a wide range of reasons, but the two most critical (yet fixable) are:

1) We assume the reader is inherently interested.

2) We drastically underestimate the role interestingness plays (especially in retention and recall).

When I say "non-reference", that's because the rules are completely different. Assuming reference materials are accurate, well-organized, and clear--whether the reader is "interested" matters very little. Reference docs don't need to be memorable. They aren't expected to communicate big, tough concepts. There's nothing to "get" when you're looking up a recipe, for example.

But when we're talking about learning--especially recall and retention--the reader's motivation means almost everything. And readers aren't even REMOTELY as interested as we might think. Intuitively, we often assume that if the reader has taken the time to find--possibly even pay for--the book, manual, tutorial, whatever, that they're obviously motivated. After all, they wouldn't be bothering if they weren't trying to learn something.

Sounds reasonsable. But it's almost...always...wrong.

Think about it. Almost nobody reading a tech document does it for intrinsically-motivated intellectual curiosity. They're reading it because they need to DO something! And anything that does not appear 100% relevant to that goal is just in the way. I said "appear", because this is the biggest issue of all. It's not how relevant a particular topic is that matters--it's all about whether you've proved that to the reader, up front. And you have to keep on proving it over and over and over.

It's not enough to simply say it's important. That won't keep their brain engaged, even if they trust you. You must show it. And you must show it before you expect them to pay attention and learn. If you want until after you've explained something to give examples of why it matters or how they can use it, that's too late.

One of the best techniques for creating and keeping interest is to make non-reference docs use-case driven. That way, each topic is framed by a context that matches something the user really wants to do. That way, each little sub-topic shows up just-in-time, instead of appearing to be there just-in-case.

The chart at the top of this post is a dramatic (albeit only partly related) study by Richard Anderson, Larry Shirley, Paul Wilson, and Linda Fielding. In the book Aptitude, Learning, and Instruction: Conative and Affective Process Analyses, they describe that they found--in some circumstances-- interest can be 30 times more important than readability in whether students remember what they read. Granted, students are often forced to read things they were never motivated by, but there's still something sobering about the results.

Consider all the people reading your docs, and ask yourself if they're reading them purely for intellectual joy, or because they're just trying to do something. Chances are, they're just trying to DO something, and it's that THING -- and not your technology (and especially not your docs) -- that they're interested in. Bottom line: if we want them to remember, we must make it memorable. And the best way to make it memorable is to make sure they're interested every step of the way. And it's usually our job, not the readers, to build that interest!

The next step on that path is to help create an interest in things they didn't know they could do, but that's another topic... : )