Search results

The Blame Game of RTFM

by Tom Johnson on Aug 30, 2012
categories: findability

It may surprise you to find that the wikipedia entry for RTFM is a actually longer than the Wikipedia entry for technical communication. For the uninitiated, RTFM stands for "Read the F____ Manual." Substitute your favorite adjective there for F. Flipping, frickin, fantastic, fine, friendly, etc.

The RTFM response captures the disconnect between technical writers and end-users. Presumably, technical writers include the information in the help material that users ask about. Yet users often don't take the time to consult the manual to find the answer. If only the users weren't so lazy, the writer thinks, and mumbles RTFM in response to their question.

On the flip side, the user thinks, if only the manual/application weren't so crappy, then I wouldn't need to ask others for the information I need.

RTFM actually has a much larger culture outside of tech comm. (Photo from Flickr.)

Reactions to the RTFM response vary a bit, but most technical writers tend to empathize with the user. For example, Wise Documentation points out that help material too frequently focuses on the basics and omits the more complicated, troubleshooting type of information that users need. Hence rather than responding with RTFM, technical writers should provide more relevant help material. Wise Documentation says,

Why is it that we write stuff that we expect others to read but are not willing ourselves to use what others have written to help us?

Much of the documentation being written today explains, brilliantly I might add, how to perform the basic tasks that are required to operate the product being documented. The problem is that this level of documentation is not needed nine times out of ten, since, at least if the product is well designed, the basics are fairly easy to work out, without recourse to the 956 page manual that accompanies the product.

...Tasks that are not part of the main flow are too often either ignored in the documentation or buried where they are impossible to find. (RTFM)

In other words, it's the writer's fault. The writer isn't focusing on important issues that users have. As a result, the user's questions are justified.

RoboColum(n) has a similar response. He asks why the user can't find the information. Perhaps the documentation could be better organized and more user friendly:

Now if I had a pound for every time I've wanted to say “Read the F***ing manual” I'd be a very wealthy man indeed, but saying that may well hide a more serious issue. The manual may well have the required answer but the question I'd be asking is, “Why is the user not using it?”. It may well be a case of being lazy but perhaps there is another reason. Is the help easily accessible? Once there, is the answer easy to find? Is it pitched at the correct level for the audience? Is the documentation user friendly? All of these, and other, questions are perfectly valid when it comes to ascertaining what is wrong / right with your documentation. (Why don't you RTFM?)

Similar to Wise Documentation, RoboColum(n) sides with the user and questions whether the help material might instead be written in a more accessible, user-friendly way.

I generally agree with RoboColum(n) and Wise Documentation, but I'll cite one more tech comm response to RTFM before presenting my own response to RTFM. Kathy Sierra outlines an approach to writing help that will better solve the user's initial frustration. She contextualizes this approach with an example involving a Nikon camera. She writes:

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. (How to get users to RTFM)

In other words, grouping similar tasks together, rather than fragmenting them in various places in the help, can help users read and find value in the manual. With better organized help topics, users will RTFM. Again, the help material is at fault.

Sharing the Blame

A great many user manuals are almost unreadable. They are poorly organized, poorly written, they omit real troubleshooting information, have tasks scattered about, skip steps, drown in fuzzy speech, and so on. Each of the approaches to improve documentation, as mentioned by Wise Documentation, Robocolum(n), and Kathy Sierra, is worth following. I have been exploring ways to increase findability and helpfulness of documentation throughout my series on Organizing Content.

However, I also empathize with the technical writer. What if you have implemented every possible technique you can fathom to ensure your help material addresses real user issues, is neatly organized, cleanly written, etc., and yet you still receive questions from users who ask the same questions answered in the manual?

In fact, just yesterday I received an e-mail from a user asking a question whose answer was explicitly mentioned in several places in the help. He could have found it by looking just a few minutes in the help. Moreover, I noticed the user's question was forwarded to me from several other people in an e-mail chain. Apparently no one who received the question thought to look in the help. Instead, they just forwarded the same basic question, as if no one had thought to address it in the help material.

Rather than continually beating up technical writers for their crappy help systems that hide answers that users would otherwise clearly find if the material were only written in English, some blame can and should be shouldered by the user. Users who immediately send off questions or contact support without reading the manual are probably the same ones who feel that any application that even needs help is poorly designed.

To those users who feel that software applications shouldn't need help, I say this. Despite what you may have read in the marketing material, much of the world is complex. Only simple tasks are so intuitive that they need no help at all. Any process requiring more than cheap labor skills requires some thought and reflection. You're going to have to do a bit of reading and learning.

Now, even if the user is somewhat lazy, it doesn't mean you should reply RTFM. The best response to a user's question that is so clearly answered in the manual is not to reply RTFM, but to simply provide the link in the manual where the information can be found. This ensures two things: First, it forces you to verify that the answer is, in fact, in the help material. This may prompt you to consider highlighting or rearranging the help material to surface this information more.

Second, responding with links to the help lets the user know that the help contains the answer, which might build some confidence in the user's ability to find the answer independently the next time he or she has a question.

If the answer isn't in the manual, you could quickly add the answer to the help material and then respond with the link. If you do this, though, be honest and explain that you just added the answer to the help so that others with the same question might find it. (Don't pretend the answer was always there unless you want to gaslight the user.)

Improvements the Technical Writer Can Make

Ultimately, help material can be improved only to a certain degree. I doubt there will come a time when learning software does not require users to exert some effort, when learning does not pose a bit of frustration and discomfort. Learning anything requires, to a degree, some mental exercise. Good documentation can make the learning process less painful and less mentally exhausting, but not completely painless.

Now that we've shared some of the blame, let's turn our attention to the technical writer. The problem may not be a poor organization of content, or poor articulation of technical concepts. You may address the most difficult and troubling issues users can possibly face in the application. The problem is that too often, technical writers feel it is their responsibility to provide information only and let the user figure out his or her plan to process it. The frustration the user experiences lies in the learning model proposed by the writer: Here is everything you need to know. Learn it. 

Learning, as I have said, requires mental exertion. It can be uncomfortable to stretch your mind around new concepts and ideas, to grasp unfamiliar interfaces and workflows and vocabulary. If technical writers want to help their users learn the material, they need to incorporate some techniques with the learning process that will ease the pain.

For example, almost all learning takes place incrementally. One progresses through martial arts training one belt at a time. One moves into more advanced phases of video games one level at a time. One learns to swim by practicing one day at a time over a series of weeks and months.

The first step toward helping users learn material in a pleasing way, then, is to spread out the learning. Sequence the material so that users start with beginning steps and move toward more advanced steps. Not everyone will follow such a plan, but for those who desire to learn, presenting the material in a sequenced way will lead to a more pleasant experience than dumping all 300 pages of information on the user at once (upon which the user immediately gives up and asks for help, and the writer replies RTFM).

Other Methods to Ease the Pain of Learning

Other methods to ease the pain of learning involve converting instructions into enjoyable movies that users can watch. A series of short video tutorials with lively, articulate narration can remove some of the pain because these videos subtract the language component. Users no longer have to glance back and forth between a set of written instructions, with various terms identifying different elements.

For example, take this sentence from a sample help topic:

On the Action Pane, in the Project Group, click the Edit icon (which looks like a pencil), and then select from the drop-down menu the project you want to edit.

Here the user has to identify the Action Pane, which is probably not labeled as such in the interface. The user must identify a nameless icon that probably only says "Edit" in a tooltip. The user must understand what a drop-down menu is, and so forth. This mental task of associating terms with their corresponding objects in the interface can be mentally straining, because you have to learn a new vocabulary to understand the instructions.

Videos reduce the need to learn a new vocabulary. The narrator simply says click the Edit icon here in the Project Group, and you see immediately where the button is, without really caring how the exact interface terms are labeled.

A Few Other Methods to Improve Learning

Without diving too far into details, I'll just mention briefly three other ways to ease the pain of learning.

Provide readers with short alternatives to longer documentation

Is it really necessary to give users a 300 page manual that has no condensed version? Why not give users a quick start version? When speaking or writing, isn't it a common practice to preface a long speech/book with an executive summary, something that gives an overview of the topics you'll cover and your general argument? This introduction provides a glimpse into the whole, and in so doing orients readers with your general direction. Quick reference guides serve the same purpose as this introduction. For more on quick reference guides, see my compilation of posts here: Quick Reference Guides.

Speak like a human

Learning can be a bore when the author adopts an official voice that squelches out all humanity. It's refreshing to see a real person explaining concepts. I'm not advocating that tech writers adopt the pseudo cool voice of the web (using terms like "ridiculously awesome" and "all manner of goodness") but instead simply avoid officialese.

Provide hands-on opportunities to practice

I'm a very hands-on person when it comes to learning. Perhaps this means I'm a "kinetic learner." My wife read an earlier version of this post and reminded me how, when we hung doors in our basement this summer, I avoided searching on YouTube for door-hanging instructions and simply tried to do it myself somewhat blindly.

At one point, to get a door to hang straight, I was about to resort to sanding the top half of the door to make the sagging door close correctly. At this point my wife begged me to wait while she looked on YouTube for an instructional video. After a few minutes she found one, and said to merely insert a longer screw into the top and middle hinges. It worked.

What is my defense for not reading the "instructions" on YouTube? I'm a kinetic learner. I learn by doing. My sanding technique worked on another door in the house, and it probably would have worked on this door too. But her solution was a lot quicker and more elegant. My point, though, is that we should provide ample opportunities for users to practice by giving them real examples, exercises, and other practice activities -- because this is how many people learn.

Conclusion

In this post, I explained that RTFM highlights a disconnect between technical writers and end-users. Usually tech comm professionals side with users in empathizing about the poor quality of manuals. The users' questions are justified.

I argued that even the best written manuals require some learning on the part of the end-user, and that learning requires mental exertion, which is hard and sometimes exhausting and painful. When we write help, we need to remember that learning is mentally exhausting. As such, we should implement techniques that will grease the wheels of learning and minimize the friction.

Some of these techniques to ease the exertion of learning include sequencing the content into progressively harder levels, providing readers with video tutorials, short versions of guides, speaking human, and providing hands-on opportunities to practice.

No doubt there are many more techniques to encourage "informal learning," as this is called. The challenge is not so much coming up with the techniques, but rather to persuade technical writers to move beyond just writing a body of information and to instead consider why the user isn't reading the manual in the first place -- because learning is hard.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.