🗃️ Archival copy:
The "F" in RTFM is the biggest clue that most of us blame the user for not reading the manual. But if "reducing guilt is the killer app", companies should take more responsibility for whether readers use their manuals. And since we can't force our users to do anything, if we want them to RTFM, we need to make a better FM.
Qualifiers: this post is about products for which someone might have--or develop--a passion for whatever the product lets them DO. So, we aren't talking about, say, watches or portable radios--although these simple products still need good manuals. Also, these tips are for those who are NOT professional tech writers. Too many times, being asked to create the manual is almost a form of punishment because the company doesn't appreciate the importance of the manual, let alone the skill (and time!) required to craft a good one.
Note: This is one long-ass post, with most of the words living in the vast cognitive wasteland known as the middle. If you look at the graphic and skim only the headings, you'll get most of what's in here. The rest is just support details.
In no particular order, a few tips on making a better FM:
Make Reading the Manual Unnecessary
In theory, "If your product is good enough, they shouldn't need a manual." In practice, that's a meaningless sentence without context. If your car radio does need a manual (oh, how I hate that mine does), blame the designers. But if your pro video editing software doesn't, then it's probably not a "pro" app. A complex product that needs a manual does not necessarily mean there's a design flaw.
If you are lucky enough to be in a position to influence a product's design, then of course you'll try to reduce the need for a manual. All the standard usability, information architecture, and user experience advice applies here (e.g. make the product intuitive, make the right things easy and the wrong things hard (to do), rely on what Don Norman refers to as "knowledge in the world" rather than "knowledge in the head", whenever possible (more on that in a minute), follow sound user interface guidelines (burn Steve Krug's ideas into your DNA), etc.)
And if are a product developer, please, PLEASE kick the crap out of anyone on the team who utters the phrase all tech writers fear and hate , "We'll fix that in documentation" -- a phrase that actually means, "We f'd up, but the tech writers will make up for our mistakes by putting a bunch of extra stuff in the manual to deal with it."
But... I wrote this post because most of us don't have the luxury of modifying (let alone designing from scratch) the products we want to help people use, so the rest of this assumes that you're pretty much stuck with what you've got.
Separate Reference from Learning
A good manual for a complex product should usually include at least FIVE distinct sections: Reference Guide, Tutorial, Learning/Understanding, Cookbook/Recipe, and Start Here. The single biggest problem with most
bad less than stellar manuals is that they're usually only reference. But even with the best index on the planet, a reference guide suffers from one huge mother-of-an-assumption: that the user knows exactly what to look up!
A reference guide, no matter how technically correct and concise and clear and all those other referencey goodness attributes, does virtually NOTHING to get me out of "P" mode if I don't even know what (or even that) I should be looking up.
If I have a specific thing I know I need to do, AND I know what it's called in the product, then I'm fine with the reference guide. But reference guides fail:
- If I have only a vague idea of what the "thing" is called that I want to look up.ORIf I don't even know the thing existsORIf I want to get better not at the tool, but at the thing the tool lets me do.(This is my problem with the Nikon D200 manual (which is actually a really good reference guide)--it helps me use the camera controls, but it's teaching me only about the camera--the thing I care least about. What I really want is to take better photos, and if the manual helped me figure out which features of the camera mapped to which cool photography things I might want to do, I'd come up the curve more quickly--which means a better chance of becoming passionate, yada, yada, yada).
1) The Reference GuideDespite the problems with having only a reference guide, it's still one of the most important parts of the manual and deserves the best you can give it including a great index, a user-friendly, relevant organization scheme (make it easy for me to look things up regardless of whether I know what they're called, etc.), and clear, concise information with visuals whenever possible. Since reference is where most manuals concentrate, and far more people are skilled at doing it, I'm not going to say anything else about it here.
2) The TutorialBy "tutorial", we mean walking the user through a concrete example of using the product to do a specific task. A lot of manuals skip this in favor of giving abstract instructions for how to do something, but not all brains can learn that way. For many people, a step-by-step tutorial is the only thing that helps them "get it." So, even though some users will never need or read the tutorial sections, they can mean the difference between a new user who actually uses the product and one who never gets past opening the box.
A few tips on good tutorials:
- Choose examples that best reflect what most new users will want to do.
- Keep the cognitive overhead as low as possible by NOT using an example that requires domain-specific knowledge. For example, a tutorial on a desktop publishing program would be better using a pizza shop as the scenario rather than, say, a tax attorney. The learner should be able to focus 100% of their brain cells on doing the tutorial and not a single neuron wasted in figuring out why that particular business would need to do that particular thing...
- Include a LOT of them. Some of us learn by "triangulation".
- Watch for cliffs! The deal-killer in a tutorial is when a crucial piece--however small--is left out either inadvertently or because the author assumed this part of the step was so frickin' obvious. Of course, the level of granularity you choose for a "part" depends on who your audience is. Most software apps today should not have to explain how a mouse works, for example; a lot of pre-existing user knowledge is rightly encapsulated in the "Select FOO from the BAR menu..." But, rarely do people complain that the manual contained too many step-by-step details. For most of us, the pain starts when we suddenly turn the page and say, "Uh... what did I just miss? How the hell did they get THERE? My dialog box looks nothing like that..."
3) Learning/UnderstandingThe more they understand, the less they have to memorize. The only way to reduce the time and pain of the learning curve is to increase learning. Too many manuals mistake reference information and memorization for learning, but we've all experienced the frustration of looking something up, doing it, and then forgetting everything the next time we need to do it again. 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.
While a tutorial is a concrete step-by-step use-case, without a deeper understanding of how and why things work the way they do, the user/learner can have trouble adapting what they did in the tutorial to their own unique use-cases. We've all seen users who end up bending and shoehorning their own work into something that more closely matches what the tutorial did, simply because that's the only way they know how to do it!
By including a learning and understanding section in the manual, you have the best chance to help users get out of "P mode and--most importantly--want to. This is where you take them from surface users who must call tech support at the first instant anything goes wrong to users who become engaged with the product and enjoy co-discovering all the ways in which the product will help them kick ass.
It is this part of the manual where the advertising, marketing, and entertainment folks have something to teach us. 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. Learning new things usually sucks at first, because it means we have to pass through the phase of frustration, confusion, stupidity, anger, etc. Most humans avoid learning anything that comes with a manual, and will try to do as little as possible to get the bare minimum level of competency.
This won't do if we're actively trying to create and inspire passionate users. We have to make this part of the manual especially enticing, compelling, seductive, entertaining, informative, useful... all without (as many of you warned) making it appear like a shallow sales pitch.
This is also where it really needs to be memorable. It's amazing how much written documentation is meant to be remembered, but anything BUT memorable. Memory is tied to chemistry, and the brain pays attention and records to long-term memory that which the brain finds important. What your conscious mind wants has nothing to do with it--this is about your legacy brain recognizing that this new thing is useful for long-term survival. And let's face it--most of the content in user manuals are far, far, far, from something the brain thinks is important enough to store.
So, we have to trick the brain into thinking that [insert widget A into widget B and configure server C...] is just as important (or life-threatening) as the tiger licking his lips outside your cave. And who better to help us make things stand out than advertisers and marketers? Entertainers and graphic designers? Really Good Storytellers? There are a ton of things that can get past the brain's crap filter, but we have to care enough to create a manual that's brain-friendly, not just user-friendly. And the brain is sooooo much pickier about what it attends to and records.
Knowledge in the Head vs. Knowledge in the WorldWhen we're talking about memory, we have to define what should be remembered, and what should exist Out There. Clearly, the more we can rely on external clues the better, and there's no reason we should have to memorize the reference steps for doing something we'll never do again, but we have to memorize some things. The trick is to figure out what. What will make their experience much better if they just know it?
Don Norman talks about defining the difference between Knowledge in the World (external clues) vs. Knowledge in the Head (things you memorize and "know"). Although he's talking about product design, it applies to manuals and to the relationship between the product and the manual.
4) Cookbook/RecipeA tutorial is a specific, concrete example. Reference is, well, reference. Learning and understanding is the place where you start to really "get it" on a deeper level. 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. It's kind of like a playlist; it rarely contains fundamentally new information, and simply groups a collection of otherwise separate pieces into one action/goal-based context.
For example, the Nikon D200 can do continuous high-speed shooting, but to do it right, you need to change several different settings on the camera including shooting mode, auto-focus, and metering. The problem is, all the different pieces you need are scattered in different places in the manual, and you have to figure out which you need only if you happen to stumble on each section and put the pieces together in your head. A simple, "How do I take high-speed shots?" or even something like, "How do I take action shots?" that described all the things you need to do... in one place... would be a HUGE help.
If page count is a concern, the cookbook section could simply list the different places in the manual you need to look (e.g. reference page 27, learning page 82, reference page 120, and the last half of the FOO tutorial). And although having to flip pages isn't as user-friendly, it's still way better than leaving it up to chance that the reader will put those pieces together on his own.
5) Start HereThere you are, with the freshly opened box, staring at this huge manual and wondering how long it'll take to just do the One Simple Thing you bought this thing for. 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. Some early success.
The problem with many Start Here guides is that they are about configuration and set-up and very little else. There's a Grand Canyon between the Start Here and... the rest of the manual. Ideally, the Start Here would go beyond the initial set-up and function as a kind of mini version of the whole manual. And the Start Here makes a great sales piece for the manual itself. "Hmmmm... the Start Here guide was great, so if the rest of the manual is like that, this shouldn't be too painful. Maybe even fun..."
Of course we've all seen Start Here guides that were total bait-and-switch--they do indeed look as if they were produced by an inspired and caring design department, but then the REAL manual looks like it was done by someone who really, really doesn't like you.
One of the best product manual goals we've ever heard is the Electric Rain "User must do something cool in 30 minues" mission. What would it mean to have a goal like that? Would it change anything about the manual?
Change the "F" in RTFM to "Fun"
Not funny, just fun. Fun as in chess. Fun as in writing elegant code. Fun as in doing something you're good at... something that lets you have a high-resolution experience. What would it mean if you asked, "How can we make the manual a fun experience?" Don't jump to the "nobody wants humour in a manual" argument--you don't need "humour" to have fun.
Change the "F" in RTFM to "Flow"
If you can keep the reader/learner/user in a flow state--where the rest of the world drops away--they'll love you. Seriously. And they'll want their friends and family to love you as much as they do. The flow experience is one of the most enjoyable and enriching times in most people's lives, and we all have the chance to help give our users just a little more of this.
There's only so much we can do if the product itself is a flow killer, but the manual can go a long way toward helping the user stay in the moment doing whatever the tool is supposed to help them do. The less they have to stop and refer to the manual (because you helped them remember how the thing works so that the next right step feels natural and intuitive), the more they get to keep doing the do.
About the right thing. Instead of caring what the user/learner thinks about the manual or even the product, care about what the user thinks about himself. Care about how the user feels during--and as a result of--his reading the manual and learning this thing. Care about helping the user kick ass. Care about giving the user an "I Rule!" experience, rather than the default "I Suck" experience we usually get from trying to parse a product manual.
Yes, this is a big "duh", but orientation is everything. When you ask someone to create a manual, be sure they know who and what it's for. Be sure they know that the goal is not simply To Accurately Document The Thing, but to Help The User Kick Ass. This one shift in perspective could change a user's world.