Creating Passionate Users Explains How to Make the Best User Manual Ever

by Tom Johnson on Mar 5, 2007
categories: technical-writing

Kathy Sierra from Creating Passionate Users made an A+ post titled The Best User Manuals EVER today. The most interesting tip was to structure your user manuals by layers of difficulty, and motivate users to progress to the next layer.

The manuals Kathy mentioned give instructions about horse riding rather than software, but similar principles apply. The article covered many points, but layers is what caught my attention. Sierra explains that good manuals are motivational; they "keep[] users willing to push forward to higher 'levels.'"

She elaborates on how the level model motivates users:

Each "level" includes a preview book from the next level, even color-coded to the new level, that helps motivate and prepare you for moving up. The assumption--and message to the user--is, "Congratulations! You finished level one! Now look at the cool things you'll be able to do in level two, and... let's get started." The motivating message is, "You can't stop now... you have all these new tools and NOW you'll be able to put them to use in these reallly interesting ways..."

The concept of levels is intriguing, but I'm not entirely sure it would work for all apps. Let's say you're documenting a software application like Dreamweaver, and you're describing how to work with tables. Do you structure your online help like this:

Level One: Warming Up
Level Two: Beginner
Level Three: Getting the Picture
Level Four: Moving Along
Level Five: Up-and-Coming
Level Six: Hot Stuff
Level Seven: Ace
Level Eight: Maven
Level Nine: Master
Level Ten: Ninja

Let's see how tables might fit into the picture. Level One shows you where the table button is and how to make a basic table. Level two shows you how manipulate tables by adding and removing columns, setting manual rows and heights for columns. Level three shows you how to structure a site with layout tables. Level four through eight show you other tasks with tables. Level nine shows you something like integrating dynamic database tables into your site. Level ten shows you how to create table mashups.

If you're a user, and you want to find an answer to your question about tables, which level do you choose? You would probably want a master index, or master TOC, at least. But that would be using the learning materials as reference only -- an error Sierra warns against. If you read help to learn, rather than just as reference, help can be structured in an appealing way as layers.

Even with the problems such a level hierarchy might pose, it's a cool concept. If you take a look at how the WordPress help is organized, it is somewhat layered. It progresses as follows:

Getting Started with WordPress

Working with WordPress

Design and Layout

Advanced Topics

Troubleshooting

Developer Documentation

Newbies pick topics near the top, and when you know the system well, you pick topics near the bottom.

Some documentation might not lend itself to a level structure. But with online help (using almost any tool, such as RoboHelp), you could structure your documentation into a series of layers, while also providing a traditional help layout — and you wouldn't have to duplicate the content.

Layering your help content can be done. But the problem with creating a really impressive array of learning materials, like Sierra describes, is that companies aren't usually hot to trot to pay for it. Kathy explains that third-party help authors stand to make a buck with this company oversight:

Until more companies recognize the value (yes, even ROI) of helping their users kick ass, there's an opportunity for the rest of us to help fill in the gaps.

Kathy expands on charging for manuals:

I'd rather see a company make top-quality manuals and charge extra, than turn out the after-thought-barely-functional docs that ship with most products today (or are posted online for most web apps).

(I believe the better approach would be to NOT charge, and exploit end-user training as a competitive advantage--remember, all things being equal, he who gets his users past the suck threshold and into the kick-ass zone the fastest wins.

Ah yes, the competitive advantage help provides. The documentation is not something to consider lightly. It has a huge impact on the product, and if your users can master your product, ever so much better for the appeal of your product.

Kathy finishes by suggesting companies slash their marketing budgets to beef up their help:

Better yet, be the first in your market to blow minds with world-class user learning materials. How long will it take before the companies that do this can start slashing their marketing budgets...

See the full post of Kathy's article. (Thanks to Rahel for pointing me to it.)

Also, a while ago I listened to a podcast by Kathy Sierra. She has a really engaging character and passion, so I also recommend you listen to her speak.