An outline for a passionate user guide

From “Creating Passionate Users,” Kathy Sierra follows up to her “let marketing write the manuals” post

Her post on “Creating Passionate Users” is a long one but well worth reading — How to get users to RT*M. Since this is a G-rated blog, apologies for the known acronym. Let’s say it stands for “Read The Fine Manual.”

As promised, I’m following up to my prior post “Seducing users to read the manuals” by taking a look at what Kathy has to say about creating that passionate user guide.

Since I’m currently working on information modeling which means analyzing content especially at the table of contents or outline model, I was excited to see her write a “model” of sorts for a passion-inciting user guide. I see a distinct tie between the structured authoring approach that we’re taking and the user learning and understanding that she describes.

So, what’s in her ideal user manual that inspires passion?

A good manual for a complex product should usually include at least FIVE distinct sections:

Reference Guide – The only way to really make it “stick” is by helping them ‘get it’ on a deeper level, where the mental model (thought bubble) in their head matches the one you were trying to communicate… the mental model that lets them extrapolate and infer and be creative about things that weren’t in the tutorial.

Tutorial – By “tutorial”, we mean walking the user through a concrete example of using the product to do a specific task.

Learning/Understanding – It is up to us to get the user/learner motivated to not just Open The Manual, but to want to actually… learn new things.

Cookbook/Recipe – A Cookbook/Recipe section is where a series of steps that might otherwise live in different places in the manual are all brought together under something like a “How do I…” heading.

Start Here – A “Start Here” section, which many product manuals include, is a low-intimidation way to help the new user jump in and get something happening.

Wait a minute… those sound familiar

If you read the rest of her detailed descriptions of each section, in essence, I believe she’s describing John Carroll’s basic concepts of Minimal documentation. Minimalism was first described by John Carroll as an instructional design philosophy at the IBM Watson Research Center in the 1980s, presented in his book The Nurnberg Funnel (amazon link).

The way I see it, structured authoring has a basis in minimalist principles. Minimalist principles encourage both us writers and trainers or instructors to:

  • get users up and running quickly (Start Here section)
  • let users think and improvise (Reference Guide section)
  • focus the material on real work, real goals (Cookbook or Recipe section)
  • make use of a user’s prior knowledge (Learning/Understanding sections)
  • use error recognition and error recovery as learning helpers (Ah ha! The one item Kathy missed out on but a few commenters noted the omission.)

I have to say that she seems to be describing consumer-product manuals, like your TiVo or MOTORAZR. I personally find it more realistic to get passionate and excited about consumer products than the products that I need to use to get my job done. Frankly, the docs I write are for products that people use to get their jobs done. So… I’m not convinced that her outline works well for the products that I document. Yet… it certainly offers some thought-provoking ideas and also makes me think, how can I work these types of sections into the docs I have? Will my particular audience appreciate sections that have the type of info that she’s talking about? Most likely the answer is yes. Wouldn’t we all like to be a little more passionate about the tools we use every day?

Lastly, be sure to check out the collection of links to her favorite education/learning blogs. Most of those are already on my RSS feed list, but I’ll be adding a few more to my list thanks to her roundup.

Viki Davis: Cool Cat Teacher Blog
Jay Cross: Internet Time Blog
Cognitive Daily
Judy Breck’s Golden Swamp
Usable Help
Darrren Barefoot
Boxes and Arrows
Solveig’s Open Office blog


  • June 20, 2013 - 6:02 am | Permalink

    Quite interesting article.
    (a) When you say “get users up and running quickly (Start Here section)” I am wondering if this had to do with one of the minimalism principles. A “Start Here” section won’t help users start quickly if it contains either a _Preface_ or an _Introduction_ or a _Preamble_… Nobody is interested in reading a “General information” section. The user wants to start using the product very quickly, he does not want to _read_ anything, he wants the answer to his question “How to set the parameters?” . Providing a precise section on “Setting the parameters” (with a meaningful title) will for sure help the user get started very quickly.

    (b) Not sure this has much to do with _minimalism_: “make use of a user’s prior knowledge (Learning/Understanding sections)”. Taking into account the user’s previous knowledge does not mean providing a “Learning section”, but preventing the author to add a section that is more than obvious to the end-user. For example, don’t write “How to brake with the brake pedal” in a manual for forklift drivers. This belongs to the “Don’t insult the user’s intelligence” minimalist rule.

    Dr. JoAnn Hackos recently detailed and updated the guidelines about adopting minimalism (worth reading!)

  • June 24, 2013 - 3:03 pm | Permalink

    Good to know! Thanks for noting and commenting on a seven-year-old post.

  • Leave a Reply