I'd Rather Be Writing » manuals

Give the Perfect Gift this Season: A Laminated Quick Reference Guide

Tom Johnson — Mon, 20 Dec 2010 07:58:41 +0000

Quick Reference Guides as Christmas Gifts

I was surprised and mildly pleased this weekend to see my sister-in-law Karin give a quick reference guide or “cheat sheet,” as she called it, to her grandma for her birthday. The guide focused on accessing and sending email in Gmail.

Grandma was grateful and elated to see the work and detail that went into the guide, which was laminated and narrow enough to prop up next to her [ancient] computer.

Contrast this happy image, passing around the quick reference guide at the birthday table and listening to the joyful chatter, with the sound of the dreaded almighty thud that large manuals create as one feels the weight and panic of an eternal instruction manual.

Karen’s quick reference guide isn’t visually engaging or attractively formatted, but she did an excellent job in bringing out all the unconscious details behind checking one’s gmail — a key detail probably necessary for her audience. Yes, this entire quick reference guide (it extends onto the backside as well) just explains how to check your gmail. She avoids jargon and tech writer slang completely as she focuses on just what the user sees.

This Christmas, if you really want to show someone you love them, give them a quick reference guide that you uniquely create for their technical frustrations.

I asked my wife — wrapping presents on the living room floor tonight — what her reaction would be if I gave her a quick reference guide on Christmas morning. She thought for a minute, and then confessed that she already knew everything, so the guide would lack value. But if I could address a relevant need, she would welcome it.

It takes me days to write these kinds of guides at work. So this is not an easy way out of a more expensive gift. And it’s hard to know exactly what computer troubles others around you have.

But maybe if you focused the guide on a soft-skills topic, such as how to get rid of stress, or how to get children to obey you, or techniques for subduing your husband, or something quirky like that, it might be an approachable and fun gift. It would be a gift she would never forget, that’s for sure.

The whole experience confirms to me yet again that users welcome short guides with open arms while continuing to despise and reject long manuals.

Blog Sponsors

Organizing Content for Constructivist Learning [Organizing Content #28]

Tom Johnson — Mon, 27 Sep 2010 13:57:13 +0000

In my last post, I argued that rhetoric is the foundation of communication. Rhetoric is the practice of fitting the message to the context to get the results you want. In the most common scenario for technical writers and instructional designers, the rhetorical context is a learning situation. You want the user to learn new software or hardware.

What’s the best way to organize content for learning? In comments on a previous post, Eddie Van Arsdall, an experienced technical writer and trainer on the east coast, commented,

I consider classroom teaching to be the best experience for understanding how people learn. I recommend that technical communicators aspiring to focus on training development and elearning spend some time teaching, tutoring, and mentoring. You’re a born teacher, Tom, as is evident by your posts.

I taught writing for about four years — two years as a graduate instructor at Columbia University in New York and two years as a full-time instructor at the American University in Cairo.

I did better at Columbia than in Cairo. As a graduate instructor at Columbia, we were trained to teach in a specific way. Rather than lecturing to students about writing principles, we asked them constant questions. About all we did was ask questions. When a student responded, we tried to get other students to respond to the student’s response, directing the conversation from student to student rather than from teacher to student.

If no one answered a question right away, we waited (sometimes a minute or more) until someone offered a response. The idea was that asking questions in a Socratic method could increase critical thinking and reasoning more than explaining and lecturing. We also gave them weekly essay assignments that required them to reason out answers and determine the best way to organize their thoughts and arguments.

I didn’t know it at the time, but this method of teaching derives from a constructivist learning theory. In constructivist learning, you don’t transfer knowledge from teacher to student in a hierarchical way. Instead, students construct their own learning through their own experiences. Students don’t learn merely from reading a textbook or listening to a lecture, but by acting and experiencing, by teaching and assessing, by exploring the topic on their own. Their experiences and what they make of those experiences is how they learn.

Teachnology, a site dedicated to teaching and technology, provides a good explanation of constructivist learning theory:

The constructivist learning theory argues that people produce knowledge and form meaning based upon their experiences. … Instead of giving a lecture the teachers in this theory function as facilitators whose role is to aid the student when it comes to their own understanding. This takes away focus from the teacher and lecture and puts it upon the student and their learning. The resources and lesson plans that must be initiated for this learning theory take a very different approach toward traditional learning as well. Instead of telling, the teacher must begin asking. Instead of answering questions that only align with their curriculum, the facilitator in this case must make it so that the student comes to the conclusions on their own instead of being told.

… Instead of having the students relying on someone else’s information and accepting it as truth, the constructivist learning theory supports that students should be exposed to data, primary sources, and the ability to interact with other students so that they can learn from the incorporation of their experiences. (constructivist learning Theory)

In other words, the teacher is the facilitator to a learning environment, but the teacher doesn’t transfer the knowledge. The student constructs the knowledge through his or her own through experiences, associations, connections, perspectives, and other insights that he or she formulates while in the learning environment.

The Example of Conferences

This learning theory rings true for the way I learn. Every conference I attend is an example of it. I’m always excited to go to conferences, to interact with other professionals in my field, to read the program and see all the topics and issues for discussion. But then I go to the presentations — all day. And then the next day. At some point, usually early on, I start to tire of going to presentations. Am I really learning something, I start to wonder? Something that I couldn’t just get from a book that I read on my own?

That’s how all conferences go for me. The problem is in the assumption that learning takes places through lectures and presentations. Superficial learning may take place like this, sitting and listening and taking notes to incorporate what the presenter says. But the real learning, the aha! moments and genuine epiphanies that make the conference worth it, aren’t anything a presenter might say. For me, it’s an insight that bubbles up on its own, through various experiences and reflections while I’m immersed in the conference learning environment. The conference provides the catalyst for the learning, but it doesn’t provide the learning itself.

This is partly why I like to interview people at conferences — because sessions don’t engage me. The lecture isn’t how I learn. I prefer to be more interactive. I want to drive the conversation. I learn by doing, acting, and experimenting. The knowledge that surfaces from these experiences is the value I get from conferences.

From Classroom to Software

The way users learn software takes place in much the same way. If you ask people how they learn an application, most will tell you they learn by doing. Patricia Blount asked this question on her blog a while back in her post When you need help, where do you go first? The responses were typical of how most people learn software:

Sometimes you do have to just wing it, though. That’s how you learn, by doing.

… When I need to learn a new product I’ll consult the user guide only as long as it takes to get the thing up and running. Then I prefer to wing it. I’ll consult the help when I get stuck…

… I use a guide to get me started with a product and to get me out of a jam if I can’t figure something out. I used to read guides because I wanted to learn everything about the product, but now I’m too impatient to learn.

That last comment is particularly telling — he doesn’t read the manual because he is “too impatient to learn.” As much as we may like the safety and comfort of having a manual, the manual isn’t how we learn a software application. We learn by playing around in the application, trying to do tasks, navigating the interface, and generally seeing for ourselves how it works. We learn by doing.

When we get stuck, we turn to the help material for the non-intuitive answers, but then we go right back into the application, because that’s where learning takes place. Users don’t learn by reading a manual and then opening an application to use it. Invariably, users prop up the manual next to their computer and use it as a guide as they explore the application.

In short, users learn by doing, and the only place to truly do is in the application.

Maximizing for constructivist learning

How do you organize your help content to accommodate learning from a constructivist approach? Here are five tips.

Move help into the interface. Put as much help as possible in the interface. If we assume users will be exploring the interface to learn the application, include tips and other help information directly within their learning environment. Little help icons and hover over popups work well for including help without cluttering the interface.

Give assignments to the user. I’m not sure why assignments are so infrequently given in manuals. Perhaps we assume manuals are for reference only and any assignment type questions would be included in a training module instead? But let’s assume you have a short introductory guide to an application. Get the user doing as many tasks as possible in the actual application. Give assignments, challenges, and other tasks that get the user applying concepts and principles that you’re explaining.

Don’t give the user a long manual. Provide an introductory getting started guide, and then put the rest of the information in a comprehensive online help or wiki. I have a colleague who recently single sourced his online help into a printed manual that was about 350 pages long. Can you imagine giving that manual to the user? Users are almost never going to read through hundreds of pages of help material to learn an application. Give them enough information (maybe 20 to 50 pages, including illustrations and screenshots) to get started in the application, and then get out of the way of their learning. Get them into the application as fast as possible. When users have unanswerable questions, they can search a comprehensive online site for answers. But avoid giving them a long PDF with the expectation that they keep their noses in the help instead of the application.

Ask open-ended questions. In the help material, rather than lay out the material so that all questions are answered, why not include more open-ended questions at the end of each section? For example, if you were describing how to enable Internet connectivity in a building, you might ask the reader the following:

Where do you think the best location to install the ISP’s modem would be in your building?
What’s the peak usage you envision for bandwidth consumption?
Imagine your most stressful event. What could possibly go wrong with the Internet connection?

You could include these questions at the end of a chapter. These questions encourage the user to start thinking about the topic for him- or herself in a more engaged way. This independent analysis and questioning will help the user learn and incorporate the material more fully than if he or she had merely read the answers in a textbook.

Provide a sandbox version of the application to explore. A sandbox version of an application is a clone of the real application, but often with dummy data. With one of my projects at work, we have a sandbox version of an application that we set up new users with all the time. It’s a great place to experiment and explore without the worry of corrupting real data or making mistakes.

Conclusion

Many technical writers are often too focused on information. We assume that users can read the manual, or sections of a guide, to learn the software. But this isn’t how most learning takes place. Learning takes places through doing — sometimes acting autonomously and without handholding in an application. Our help should reflect that learning behavior. If it doesn’t, we’re merely writing reference material that would fit into an encyclopedia.

Blog Sponsors

Chrysler Drops Long Car Manuals in Favor of Short Guides + Video

Tom Johnson — Thu, 01 Oct 2009 05:46:03 +0000

Chrysler moved their car manuals from the traditional thick paper manual to a shorter format accompanied by a DVD. Chrysler says the switch will not only save 20,000 trees a year, the videos on the DVD will also be more helpful to users trying to perform tasks. The shorter quick reference guides will still be 60-80 pages long (judging from the photo below, they also look more attractively designed).

Chrysler's new documentation strategy: short guides + video + DVD

With my emphasis on quick reference guides and video tutorials, I feel like I’ve followed a similar move as Chrysler’s. I do like to have a car manual in my glove box, but only for simple, quick information — what type of oil, what does this or that light mean, how do you change a bulb, etc. I don’t need to know the full array of reference information. When I need that info, I can look it up on a computer and print off the relevant topics.

(There’s a brief discussion on the latest New York Times Tech Talk podcast about the move from paper manuals to DVDs.)

Blog Sponsors

Users Read Help Manuals Like an Encyclopedia, Not a Novel

Tom Johnson — Fri, 19 Sep 2008 06:13:03 +0000

On Linkedin, I’ve been reading an excellent thread of answers to the question, “Do you read user manuals?” Of the 50 people who answered, the resounding response is No, I don’t read the manual. I try to figure out the application on my own. I only turn to the manual when I get stuck and can’t figure out a feature. Or I turn to the manual when I want to learn more advanced functions.

One of the responders, Robert Poulk, put it best when he compared manuals to encyclopedias:

You’re asking a variant of the question “Do you read the Encyclopedia?” The answer is, of course, yes, but only the parts that matter.

I think if you go over the other answers you’ll see that’s really what everyone is saying — “Yes, but only the parts that apply to whatever I don’t understand at the moment.”

A good user’s manual useful it not only contains good information about everything a user may come across as the product is used but also, and more important, a means to locate the information easily, meaning randomly.

IMHO people need to stop being embarassed about not reading the whole thing. Nobody does, and nobody should.There’s no need to read the whole encyclopedia in order to learn where the Ganges River is.

In other words, users turn to the help to look for a specific question, just as someone consults an encyclopedia for a specific question. No one reads the entire encyclopedia/manual, nor is anyone expected to. Well-written encyclopedias allow users to find information through indexes, tables of contents, alphabetical organization, and search fields.

Reading these responses, it made me wonder I should adjust the approach to my help’s home page. Usually, my help’s home page provides an introductory overview of the application. Most of the time, users are already familiar with the application, so this introduction is really just filler material.

What should really be on the help’s home page? The top ten most common questions users have about the application. The first page users see should try to anticipate answers to the obstacles they encounter. A search box should also be readily visible.

In a previous post (“How Much Should You Document?”), I explored the question of whether we document too much, whether the resounding thud of a thick manual is a turnoff to readers. Reading this LinkedIn thread reinforces the idea that users need all the advanced nitty gritty detail that help provides. In simplifying the help, we may leave out the answer to the complicated question the user is trying to answer. A comprehensive online help file, or a three-inch thick manual, is all right if the user can navigate it via indexes, tables of contents, keyword searches, or other means to quickly find the answer he or she is looking for.

How Much Should You Document? Everything? Strategies for an Agile Environment

Tom Johnson — Wed, 10 Sep 2008 03:19:28 +0000

In a recent IT Author podcast (“Documentation and Agile Development“), Alistair Christie and Graham Campbell talk about agile development and its impact on documentation. One consequence of working in an agile environment, they say, is the need to prioritize your documentation, to deliver instructions for only the most important or confusing features.

Presumably, some agile environments move so fast, you have to triage what you document because there’s no time to document everything.

How much should you document? Everything?

Alistair explains that you can’t document everything, and he quotes from Martin Fowler’s “The Almighty Thud.” Fowler, however, takes the argument one step further, arguing that you shouldn’t document everything. Fowler writes,

If you document everything, you are giving everything an equal weight. Do that for a complex system, and you are buried in detail. In any system there are some aspects that are more important than the others, key aspects of the system that once understood, will help someone to learn more. The art in documentation is to find how to document these aspects as clearly as possible. In this you emphasize these areas, and leave the details for the code.

If you document everything, you end up giving everything equal importance and losing focus on the key tasks and concepts users need to learn. You need a focal point, a selection of core tasks that receive prominence and make everything else intuitive.

Fowler continues, citing his own approach to the article he wrote as an example:

As I started to write this article I was overwhelmed by the things I could talk about. Lots of anecdotes and tips came to mind. But I know that to get you to read and remember this article I could only talk about a few of them. I had to select the key things that I had to mention. Communication is all about that. The key to good communication is to highlight the important things to say. Saying everything is not communication. That just passes the selection of the important things onto your readers, and discourages them with a heavy document. That selection of information is one of the most important parts of communication, and it is the responsibility of every designer.

I agree that selection is key to crafting any article. Were his article 20 pages, I wouldn’t have read it so eagerly. Instead, because it’s 2 pages, I did read it.

Alistair says that when you give someone a huge manual (one that makes a thud when you set it down), it makes the user’s heart sink. “They don’t think, Oh, that’s great. No, they think oh, This looks grim.”

Bloating the table of contents with dozens of non-essential topics reduces the focus on what customers need to be concerned about. Each additional word you add dilutes the importance of the other words. “The more you document, the less people read,” Alistair says.

We all know that if you give someone War and Peace, they’ll probably never read it. But give them a short story and they read it the same afternoon.

No one disagrees with brevity. Almost all users want concision. However, writing an article is different from writing a help system. In a help system, I do think almost all the features should be documented — somewhere.

If you limit the help topics to just the core topics, what happens when the power users search for an advanced question and find nothing? What happens when Joe user wants to know how X widget functions? Is our response simply, “Sorry, we didn’t think that feature was important enough to document”?

Fortunately, this whole dichotomy between (a) documenting everything and overwhelming the reader and (b) selecting what to document and risking absent information is an Either-Or fallacy. It is possible to both document everything and give the user a brief guide. Simply, document everything in the online help. Then create a quick reference guide to give to the user.

Am I missing something?

To avoid the disheartened look on a user’s face as the two inch manual makes a thud on his or her desk, reduce your printed manual to a much smaller subset of the online help, rather than duplicating it. Remove all the low-priority topics. Let the reader know that full documentation is in the online help.

Since users don’t typically read manuals anyway, they’ll welcome this approach. No one has ever said to me, Tom, this guide feels a little thin. Couldn’t you add more to it?

Fowler’s advice to avoid documenting everything may reflect what he was documenting as well as his time. Fowler was documenting code, which has layers upon layers of depth. But he didn’t say to leave out documentation, just to “leave the details for the code.” You can add little notes here and there in the code using slashes.

Also, Fowler wrote his article back in 1997 — more than 10 years ago. At that time, I’m not sure he had all the single-sourcing capability we currently have. Perhaps producing subsets of documentation (or multiple manuals for different roles) was too difficult.

I’d be curious to hear your approach. Are you over-documenting? What’s your approach to reducing the “thud” while still delivering complete documentation?

Additional Resources

Listen to this Boagworld podcast for details on agile methodology.

Read this post on extreme technical writing from a tech writer’s point of view.

The Blockhead Blog: Beware the Default Manual

Tom Johnson — Tue, 12 Aug 2008 23:08:32 +0000

The Blockhead Blog: Beware the Default Manual.

The Kind of Documentation Users Really Want

Tom Johnson — Mon, 16 Jun 2008 05:13:26 +0000

Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce.

But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help.

(I’m surprised how many people actually tell me that last option, as if in any kind of world that would be feasible.)

The most common responses go somewhat like this:

I like to jump into the application and then turn to the help material when I get stuck.
I want to quickly search the help to find an answer to my question.
I would like the videos sent to me on a DVD please.
I like to mark up the printed manuals with notes and tabs.
Videos appeal to people who are visual learners. I prefer to have both video and print.

While it seems like such a simple task — ask the users what they want, and then deliver it — in reality it’s a difficult call. Imagine that you’re planning to feed a large hall of people. In deciding what to feed them, you ask them. But the responses are all over the place: some are vegetarians, some love steak, some prefer barbeque, others want salad, others want pork, others don’t eat pork, others like pizza, others want crab, others are allergic to seafood, and so on. Same goes with help.

However, despite the variety of learning preferences, I think there are several key principles that hold true for almost all of us:

Long manuals intimidate us and bring out a sense of disgust and depression.
Short quick reference guides, cards, or other quick material give the impression that the application is easy to learn — therefore we welcome short guides with open arms.
When we have questions, we prefer to search for the specific answer rather than reading a manual from the beginning.
When we don’t find the answer within 2 minutes, we give up and ask our neighbor or call someone.
Seeing a process is often much more useful than reading about it.
Visual images with callouts and other annotations make instructions easier to absorb while scanning, and our primary reading mode for help materials is to scan.
If undergoing training, hands-on tasks at a computer lab are infinitely more valuable than a long demonstration at the front of the room.
Videos are helpful, but if they’re long, or if the user has no control to skip around, fast forward, or go directly to bookmarks, a long video tutorial (more than 5 minutes) is unbearable.

Given this variety of ups and downs, usability principles and learning preferences, what set of help deliverables will most likely appeal to the widest audience? In most situations, one can’t create them all and do a good job. Maybe you’re magically able to single source everything into 7 different deliverables at once and satisfy everyone, but in my experience, that doesn’t really work.

A Telling Moment

My favorite response to the question — “How do you prefer to learn new software applications?” — was when a user pointed me to the Interactive Microsoft Office Guides. These guides were created my Microsoft to help people figure out where all the supposedly intuitive stuff is on the ribbon (I can just see the Microsoft ribbon developers saying, 3 years ago, “Oh users will get it, totally ….”

You might want to take a look at these guides. They’re Flash-based, interactive, and really engaging, not to mention helpful. They show a mock interface of the application. When you make a selection, it gives instruction on how to do the exact same task in Word 2007.

My Analysis

When it comes down to it, here’s what I think most users truly want:

A comprehensive online source they can search and quickly find answers.
Short quick reference guides (about 3-5 pages) in an attractive format.
Short 2-minute video tutorials for the most confusing tasks.
An ability to interact or contact a real person either virtually or physically.

Notice that I omitted the M word. There isn’t a 200 page print manual in the list. I have mixed feelings about this omission. At the last STC Summit, I attended a panel that discussed whether the printed manual was dead.

Unfortunately there wasn’t a definitive answer. When you omit the printed manual, 67% of the people complain, according to the panel. But apparently if you put the manual in PDF format, in place of a printed manual, the percentage of people who use it is exactly the same. So people don’t use the printed manual, but they complain if you don’t include it.

Creating a long manual is no easy task. To be usable, it needs a meaty index at the back that is thorough, full of synonym references and other user-intuitive phrasings. Additionally, you need cross references throughout. And then there’s a lot of layout and formatting. If you have images that you’re including, the resolutions differ from online and print, so often you need two sets. In many cases (if you’re using a good help authoring tool) you can mostly single source your online help to printed material in one go, but setting up the conditional tags, print styles, variables, cross references, and other considerations in your tool, as well as fixing the inevitable formatting errors, takes a long time.

Rather than labor away at this printed beast, I think I will, for once, skip it and focus on improving other deliverables my users more frequently request.

What help deliverables are you creating for your users and why?