RTFM: Acronym Whose Time Never Came
Today I actually saw the acronym RTFM in a post about learning how to use a software application. You remember that one: Read the F**king Manual. I should say that the author of the post used the acronym lightly, not as a put-down. Nevertheless, if you produce a manual for your software or hardware with expectations customers will read it, you are seriously mistaken about a lot of things related to technical learning. I used to write manuals for a living. I don't write them anymore, because for the most part, people do not find them useful.
I should define what I mean by a manual. It takes the form of a book, often fifty pages or more. These days it is usually a PDF, though other digital formats are possible. It has front matter and back matter. The table of contents reveals the book's organization. Organization of chapters and sections is linear and rational, sort of like a school curriculum. You read stuff in the front before you read stuff in the back. It is not organized like a cookbook, where you find the recipe you need and ignore the rest. In these ways, a manual differs from the various online learning systems that people have developed over the last decade or so – online learning systems where you find the recipe you need at the moment, and use it to solve your current problem.
Food processor, and a bag of CDs
Let me tell you a story from the holidays, when we visited family in DC. My wife and son were in the kitchen, preparing dinner. My son, as savvy about equipment and technical requirements as they come, and a good cook to boot, pulled out a new food processor that had seen little or no use. Food processors have interlocks to prevent them from operating until every part is perfectly aligned. If you sell an appliance with a whirling blade inside, you want to keep customers safe – then they don’t sue you. The blade does not turn until you fit the bowl, cover and base together in some secret way that only the designers know. I say secret because for this model, designers of the appliance placed no markings on the parts to show how they fit together.
Everyone who uses a food processor knows about interlocks. You have to pay close attention to each part to find the magic fit. Yet the designers apparently wanted to make a puzzle out of the whole thing. They made proper alignment as counter-intuitive as they possibly could. They might reply to queries and complaints, "read the manual," but it would be a poor response. You do not need a manual to assemble the pieces of a properly designed food processor. People do not save manuals for all the appliances that arrive in their house. When you have some vegetables you want to slice, you don’t want to go search for a booklet that you’re not even sure exists anymore.
Eventually my son Googled the answer to the problem from his phone. It took a bit of research, but I expect he thought, "I should have done this earlier." The manual is the internet. Google is your gateway. Ask your question and someone out there probably has an answer for you. You can find your answer faster with your phone or computer than you can with a manual, packed with safety warnings, that a manufacturer published to comply with legal requirements, or to fend off personal injury claims. If you want your customers to use your learning materials, they have to be superior to – and accessible as – the internet.
I think about these things because I worked for a company not so long ago that produces manuals for its laboratory instruments. It ships these manuals as PDF files on compact disks. It observes punctilious but ultimately pointless procedures to prepare these doc CDs, in order to deliver documents right in the box, with the instrument. Since the equipment requires special knowledge to set up and operate, they sincerely hope customers place the doc CD in a computer, find and open the correct PDF file, then turn to page one before they do anything with the equipment. Customers will be happy because their expensive new instrument arrives with thorough instructions.
How do customers actually behave when they unpack their equipment? They typically throw the plastic bag full of CDs – disks full of drivers, lab applications, and documents – up onto a shelf! They don't even open the bag, let alone find the doc CD. Instructions in a manual that comes in the box may comply with government regulations – regs written decades ago – but it does not comport with the way people learn now. When was the last time you bought something new, and learned how to use it by reading instructions from a manual stored on a CD? We have better teaching and learning methods now.
More disheartening, people at this conscientious company did not grasp the fate of their carefully prepared documentation, until they observed customers unpack a new piece of equipment. You can't criticize the effort required for first-hand observation, but the company was stuck in a doc time warp from a generation ago, when CDs were bright and shiny and gee-whiz. Even after they saw what happened to that bag of CDs out of the box, they continued to deliver their documents the same way! You remember when companies used to send CDs in the mail. We threw them out, and that was when CDs were attractive. Send your customers a CD now and they'll think, "What, they want me to load this up in a CD drive?" You may as well send a five-and-a-quarter inch floppy disk for a drive they've never seen.
Do not depend on CDs, paper manuals, or anything not easily findable with a mobile device, for your daily bread. Your hard work will wind up on the top shelf, unopened and unread. Find a way to teach customers how to use your products some other way, because they will not RTFM. The people who invented that acronym thought they were cool and a bit superior – techies who already knew it all. Maybe they did know a lot, but it's not cool to use a profane put-down to remind others that you know more than they do. Neither is it cool to hand your new customers a fat PDF with tons of information in it with curt advice: "Here, come back after you've read this." You have plenty of competitors who understand how to manage technical learning better than that.
How to reach your customers with information they need
Response to my article about manuals was swift and sure. One thing you can say about digital communications: it is fast and people let you know what they think. More than one respondent said that manuals still have a place: many customers want to see them as part of a company’s communications arsenal. Others generally agreed that manuals don’t readily fit the learning methods that have developed in a digital environment. Here are some remarks from Ellen Ashdown in the latter category:
"I think I own that food processor. The food processor tale is also a story about lousy product design, which can't always be fixed by good documentation. In my experience, a typical user interaction with documentation looks like this: 1) customer experiences a problem; 2) customer attempts to figure it out; 3) customer gets frustrated; 4) customer figures it out, quits in disgust, goes to the documentation, calls or emails support, or goes to another source, such as Google.
"If they go to the documentation, most people have a specific topic or question, and need to be able to locate that and only that information quickly, or they choose another option. If you're constantly telling your users to RTFM, look for gaps in your documentation and training, and in how you're presenting your data.
"Information design and the user experience for documentation is still a huge gap for a lot of companies. If you understand how and why customers go to the documentation, you can make it easy for them to get their answers in the shortest time possible, which is what they want. It may be quite different for each customer, which is why single sourcing is such a great tool. You're always going to have customers who want to get the answer from a real person, and whose first reaction is to pick up a phone to call your support team. That's never going to change.
"In light of that, here’s a worthy practice. Distribute your documentation to your field support team in an organized way. Then, when customers call in with a question you know the answer to, your team has exactly the information they need to give them the answer right away. It adds value to your documentation when you use the same content your team generates for clients, to provide information to your customer support team. In this case, the content serves as a knowledge base or support reference system for field application engineers, and every other person who helps customers succeed with your company's products."
Hearty thanks to Ellen for well articulated comments!
Two war stories
Now let me tell a couple of war stories. War stories are great, because they tell how you fought the good fight, and you’re the hero of the tale. Your listeners may not believe you, but then, they weren’t there.
I tell these stories with an emphasis on process. In both cases, I was the tech pubs manager, and a one-person shop, so I had an interest in those issues. In the first instance I tried to change the company’s practices, but too many other factors interfered to make the effort successful. In the second instance, I just had to be patient to see things work out.
Let's start with company X, in the semi-conductor industry. The company designs chips that serve as the controller – the central processing unit – for multi-function printers. It tests those chips on a variety of reference boards, but in the end, engineers who design printers need to make those controllers work in their own companies' products. That means company X supplies essential information about the chip to their customers’ engineers, so they can design and build high-quality printers around the chip.
Well, the company supplied essential information and then some. The chip shipped with a heavy register specification: nearly eight hundred pages of small print. It came with a software development kit, accompanied by a manual over twelve-hundred pages long. The Where's Waldo problem for customers was huge. The nugget of information they needed at a particular point in the design process hid under a mountain of distracting data that had no relevance to the engineer's question of the moment. The engineer would call for help, often from the other side of the world. Sometimes the implicit response to his query was, "Have you read the register specification?"
You do not want to ask a question like that of your customers! They are stuck. They do not want to sift through an amazing amount of data that you threw at them because you did not want to trouble yourself to decide what customers had to know, out of all the material that proved useful at some point during your own design process. Customers do not need to know everything you know.
I'll admit that boiling down the register specification would have been a time-consuming process. A company could easily say that it was not worth the benefit, especially since it wanted to have that information on record for its own engineers. What customers really needed, beyond the chip's pinout diagram, was accurate, crisp documentation of the API supplied in the software development kit. That information could have been distributed right with the API’s files, and produced online using an open-source tool like doxygen. Then design engineers could easily find information they need to make other circuitry and components communicate with the printer’s controller. You want to integrate essential information about how to use the API’s functions into the software development kit, not roll it up in a separate, twelve-hundred page PDF.
The company did not care to do it. Not so surprisingly, company X's desire to make its controllers part of millions of printers worldwide did not work out.
The second story is easier to tell, as it's a success story from the doc point of view. Company Y sold a set of tools to develop and transform platform-independent, embedded software. You could use the toolset to write detailed specs for the software, right down to signal pathways, then transform that model into code for a specific platform. For instance, you could develop embedded software for missile radar systems, which perform the same basic function wherever you find them, but operate across a large number of electronic environments.
The company decided to use a software development environment called Eclipse to prepare its toolset for commercial distribution. That was a good choice: anyone can download Eclipse from the internet. IBM supports it, so it works well. Most important, it was well adapted to requirements for the toolset's distribution. Among those capabilities – a great benefit for me, the online help developer – were effective documentation tools. You could readily create a table of contents using XML, and you could prepare help topics in the same environment as the toolset. You did not even have to look far for a template, as Eclipse's own help system served well as model for other online help topics you might want to develop.
Company Y's experience illustrates what you want to go for when you make a decision about development environments. You want your customers to have the information they need a couple of clicks away: don't make them look around for CDs, read long PDFs, and especially no Where's Waldo searches once they have the correct document open. Again, if your customer support efforts can't beat Google, you're in trouble. You have to supply better information, and faster, than your customer can obtain with a Google search. Your documentation ought to be so concise and interactive, and so accessible, that it helps customers refine their questions as they search for answers.
That's enough for stories. It is actually not that hard to answer people's questions. Organizing information for complicated, sophisticated products, and delivering it properly is difficult. Developing processes that communicate information in flux to customers whose own needs change is difficult as well. Yet we have tools to accomplish these things, and we have not lost our appreciation of simplicity whilst we harry ourselves with complicated problems. We can still be mindful of how to make things work.
Concluding thoughts: good housekeeping
We’ve talked about document formats – PDF and HTML in particular – and the processes required both to develop and to distribute different types of publications for customers. To start, we suggested that you should not expect your customers to read traditional manuals in order to use your products. Then we discussed alternate processes and formats to communicate technical information to customers. That's the goal after all: communicate essential information to people who want to benefit from what you sell.
I’ve saved some take-aways for our conclusion. Let’s finish with a look at several housekeeping matters to remember as you manage digital content. These principals apply to management of all kinds of material, from traditional manuals all the way to what I think of as distributed information. We all want our mental spaces along with our living areas to be clean and tidy, with items we need easily retrievable, and basic processes on automatic. These goals naturally apply to digital content management. Here are five practices to follow:
- Develop consistent file naming conventions and storage principles. Then you can scan long lists of files and folders, or enter search terms, with confidence you will locate exactly what you need.
- Streamline production processes. Design them for accuracy and speed. That means simple, easy-to-maintain templates; simple, easy-to-follow procedures; and unobtrusive error-checking for quality assurance.
- Use a version control system that runs in the background, and integrates well with your other tools. It should be especially well adapted for document control.
- Do not maintain two copies of the same content in two different locations. Single-sourcing across an entire enterprise is still a holy grail, but you can practice it in your own domain. If you need to make an update, make it once, in one source document.
- Pay attention to your primary distribution channels. If your audiences – external and internal – tell you they do not have required information, when and where they expect it, look for shortcomings in your production and distribution plan.
These five practices sound self-evident when you write them down, but in fact they are a challenge for large companies, and for those still growing. Why do practices that stress accuracy and speed seem to become complex so readily? Well, people come and go, products and marketing strategies change, some tools work well and others do not, leadership and working groups change, customer requirements push companies in multiple directions, internal conflicts and tensions develop. If problems come piecemeal, so do the solutions.
In that shifting environment, complexity even looks attractive at times, but mostly companies try to maintain simple, consistent practices. The simplest and most consistent way to accomplish tasks appears to be the way you accomplished them in the past. With ambitious plans, which include beating the competition, merely doing what you’ve always done fails you. It does not permit plans that take changes and unexpected circumstances into account.
Competitive, forward-looking firms account for change in all their business plans. Otherwise you wind up hamstrung with procedures and tools and tired practices that used to work, or that someone thought would work, but that only cause problems when you try to meet challenges coming into view. Among those challenges, communication strategies and practices occupy a central position. If they don't work, little else does.