« Introducing my new co-blogger | Main | I heart slashdot!!! »

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... : )

Posted by Kathy on March 31, 2006 | Permalink


TrackBack URL for this entry:

Listed below are links to weblogs that reference Two more reasons why so many tech docs suck:

» What's More Important for Retention: Interest or Readability? from SmartTechWriting
Most of us would probably say readability, but Kathy Sierra makes the point that it's interest, and by a huge margin!Technical writers focus on readability by nature. Isn't our primary task to make the complex, simple? But for the documentation... [Read More]

Tracked on Apr 3, 2006 1:26:37 PM


I find the use case method quite boring. They make you read through a lot of setup you don't care about to get to the information you do care about.

The ultimate organization is the FAQ. It's just an index of the do questions.

Posted by: penny | Mar 31, 2006 11:41:01 PM

I usually flip right to the use cases, but it's disappointing when the author has chosen too obvious examples to demonstrate. I guess it's hard to choose between simpler use cases that will apply to more people and arcane cases that teach some users more.

Use cases are especially dangerous in Photoshop tutorials. Every image has its own nuances, so a fifty-step tutorial on how to make this landscape look good won't apply to most of your users' photos.

Posted by: Drew Bell | Apr 1, 2006 5:37:18 AM

This post like so many others is why I always read your blog.

"readers aren't even REMOTELY as interested as we might think" - Right! But you never blame the readers, (or in my case the "listener") for not being interested. You argue for making it interestig. (we can always blame the "so-called learners" over a beer some night when we are feeling bad for ourselves)

Case uses; interesting, boring or helpful? A tactical issue. But the "issue behind the issue" - are we who stand and teach, or write (in whatever field) willing to own our contribution to learning? Do we really want to free others to "kick butt"?

Posted by: Michael Wagner | Apr 2, 2006 5:52:37 PM

People who sell for a living have long known how important maintaining interest is. Before I became a technical writer, I was in the fitness industry. We knew that the reason why people didn't join is not because of the money, or because we didn't offer a particular piece of equipment. It's because between the time that they walked in the door and walked out the door, we somehow failed to not only maintain, but heighten, their interest.

Good post, Kathy.

Posted by: Jeff | Apr 3, 2006 1:17:27 PM

Kathy, you haven't said anything unique in your post. Technical writers, Don Norman, JoAnn Hackos,m Saul Wurman, Saul Carliner, have all written similar material on peaking user interest through a variety of ways (not just Disney landing) in technical documentation.

Posted by: Jennifer | Apr 12, 2006 3:35:38 PM

Good points, as usual, you guys.

I wasn't clear about several things, I can see now. For one, when I say "use-case driven", I don't mean that you actually have to *write* them as use-cases, or even tutorials. What I am referring to is more about how you decide to structure the narrative of a book/doc that is purely for learning and NOT for reference. Cookbooks, hacks, etc. are still a form of reference. This is about deciding how you will take people from zero to wherever they need or want to be on a cognitively challenging topic. [These things don't matter much when the content is easy to grasp and/or remember]

Michael: "are we who stand and teach, or write (in whatever field) willing to own our contribution to learning? Do we really want to free others to "kick butt"?"
Ouch -- I think you got right to the heart of it. Well put.

Jeff: yes, yes, yes. [I spent 10 years in the fitness industry as well -- that's where I first started writing software. And I agree, the importance of motivation is ultra clear in that domain.]

Jennifer: I agree. If I implied I'm saying something *new*, I don't mean to. I was teaching a class in this myself (UCLA entertainment studies) almost 15 years ago, so even my own *perspective* on it is not new. And I'm actually in the credits of Don Norman's Design of Everyday Things CD-ROM because they used one of my checklists for how to maintain interest (and other things). So I'm very much aware--and quite grateful--for those who HAVE been writing about this.

What I believe IS unique here is that in the technical documentation world, these things have not previously been implemented on anywhere remotely near the scale that Bert Bates and I (and more recently, our other authors) have done with the "brain-friendly" series we created for O'Reilly.
So while indeed everyone was *talking* about it, almost nobody in commercial tech books was willing to DO anything about it. We decided to take what these smart folks like Norman, Wurman, and Schank have told us we should be doing and actually apply it, and prove that it can be very successful for helping users learn. Today our books represented 4 of the top 25 bestelling computer books on Amazon, and 3 of O'Reilly's top 8 bestsellers. As I've said here many times, we aren't skilled or particularly creative writers, so we're pretty damn certain that if it's not our writing ability, it must be that the science behind the format does exactly what it's supposed to do--make learning more effective. We're the implementors, not the innovators.
So, is there anything unique in what I'm saying? No. But in our domain, we have a unique *perspective* from which to be discussing it, and we're highly motivated by the idea of helping others do the same. That's how the topic of this blog all began...

I'm thinking that you haven't been reading much of this blog, or you'd have seen that I've mentioned Don Norman so much in the last year that someone in comments finally told me they were sick of all the Norman references ; )

But your comment was a good reminder that I need to repeat these references for the new folks.

Posted by: Kathy Sierra | Apr 12, 2006 8:51:11 PM

This is so true. I've Continually preached that only 7% of oral communication is the actual words, the remainder is tonality and body language.

A good teacher can teach anything. A good writer can write about anything. The method of expression is vital. The layout is critical. In the thrill of writing minutia we lose the ecstasy actually teaching somebody something.

Posted by: Vicki Davis | Apr 13, 2006 4:51:58 PM

The comments to this entry are closed.