AskTog: Interaction Design Solutions for the Real World
 
Interaction Design Section   Living Section   About Bruce Tognazzini
NN/g Home > AskTog > Columns > How to Publish a Great user Manual Ask Tog, November, 1998

You may be a writer; you may be looking for a writer. Either way, you will find what you need in:

How to Publish a Great User Manual

Links in this article:

When was the last time you curled up in bed with a really good user-manual just for the sheer joy of reading it? Never? Think that is some immutable law of nature, like the one that dictates all textbooks must be dull as dirt? 'Tain't so, McGee.

Conflict Catcher is a must-have utility for anyone doing serious work on the Macintosh. It makes visible and helps troubleshoot the myriad mysterious add-ons that clutter the Mac OS. It has the perfect profile for being shipped with a manual that is both dull and unintelligible, but, apparently, someone screwed up, because it is shipping with one of the most witty, delightful, and lucid manuals I've ever come across. Good enough to read just for the sheer pleasure. Why? Because its author, David Pogue, is a gifted writer—always an advantage—and because he has followed the principles of manual design that ensure success.

Steps to overcoming RTFM

Software manuals tend to come in two flavors—dull and unintelligible. This has led directly and inexorably to RTFM!, the rallying cry of technical support people everywhere. Yet twenty years of yelling at callers to Read The Freaking Manual (or words to that effect) hasn't helped. Fixing the manual does. Follow these five easy steps, and your company will start saving big-time on the cost of customer support.

1) Supply a (real) manual.

An amazing number of companies rationalize their way out of supplying a manual at all, then complain as loudly as anyone else about the stupid users calling customer support.

A manual, since many people apparently don't know, is made of ground-up dead tree. Those delightful little PDF files that people insist on including on their CD ROM don't make it. First, my experience has been that Acrobat only opens around 40% of the time. (The rest of the time either it is distressed because it can't find some infinitely important font it wants or I've already got as many windows open as the OS can handle.) Second, even when it does open, these electronic manuals are not only difficult to read, they are anything but portable. (My 20" monitor is way to heavy to crawl into bed with, and I hate trying to read 400 page print-outs.) Besides, I just spent $395 for this software, and all you gave me was an 89-cent piece of plastic? Get real!

A dead-tree manual necessary to the use of the program is the ultimate piracy-defeater. Pirates will blissfully copy your CD-ROM, they will blissfully upload your code to the newsgroups, but they won't Xerox the manual. It's not that they can't; they just won't. If you scrimp on the manual, you may still retain market share, but you won't be selling a lot of software.

Some folks have found a clever way to drive people to piracy even while supplying a dead-tree manual. We now have the spectacle of major software houses, including Microsoft and Apple, turning out atrocious manuals in the full expectation that users will buy "real" manuals in the bookstore, so the users can actually figure out how to use the program. These manufacturer's junk manuals typically display the characteristics of an edited feature spec, with no thought as to structure. (Sometimes the features are just listed in alphabetical order!)

What a great technique for inspiring piracy: Anger users with a stupid, useless, paper manual they may spend days failing to understand, then force them spend lots of additional money buying a lucid, third-party manual. These people's advice to others? "Steal the software and spend your money instead on this really great manual I found down at the bookstore."

Conflict Catcher 8 comes with two manuals—one where you learn about the program and one other really skinny one you use when your system has gotten in trouble and you are using Conflict Catcher to help straighten it out. Both are complete, both are lucid, both are all you will ever need to use the program, and both are essential.

2) Explain the problem being solved

A lot of bad manuals out there are actually good feature specs that companies have just translated from engineeringese into a human language, then shipped. The problem with this approach is that you end up with a manual that explains every feature in depth, while keeping secret why anyone would ever want to use them.

Programming language manuals are almost universal in this failing. They present 100 or 200 different commands without once mentioning what they are useful for. The human mind doesn't work from disembodied specs. Humans find it extremely difficult to store free-floating information. Explain a problem and offer a solution and people will remember it forever. Jump right to the solution, without ever presenting the problem, and it just won't penetrate.

Let's examine this shortened excerpt from David Pogue's Conflict Catcher 8 manual on the subject of building a new system folder:

One of the most important troubleshooting tools is the clean system install—which means giving your Macintosh a brand-new system folder, straight off your Mac's original CD….Your new system folder is guaranteed to be free [of] corruption. Unfortunately, it's also guaranteed to be free of any useful enhancements….Before Conflict Catcher 8, the final step in the clean system install process was the tedious business of comparing, side-by-side, the contents of your old system folder with the contents of your new one….Only after you had performed this time-consuming comparison would your Mac be ready to go….Fortunately, Conflict Catcher 8 greatly simplifies and accelerates this…process.

By the time the user has finished reading the original five paragraphs from which this is drawn, they understand why they would want to do a clean install in the first place, what problem arises because of a clean install, and what Conflict Catcher 8 is prepared to do about it.

David goes one step beyond, however, by "selling" the product. That might seem silly, since obviously the person has already bought the product. However, when the reader understands that Conflict Catcher is going to eliminate for them a task that traditionally took three to four hours of the most boring, tedious work imaginable, they are going to get excited. Excited enough to tell their friends about Conflict Catcher. Excited enough even to write an article about it.

Users now understand the motivation for the feature, as well of the value of the feature. Their minds have become fertile ground for the explanation of how to use the feature. A single reading will now transfer better than five readings would have in the absence of this understanding.

3) Present the concepts, not just the features.

Well-designed software should be centered on a few, large concepts. HyperCard, Bill Atkinson's hypertext forerunner to the browser, had a single, underlying concept. Get that, and you got HyperCard. Miss it, and you were lost. The concept centered on layering, with both the background object, the "card," and objects place on the card each having several specialized layers.

The HyperCard manual began with an exploded diagram of the layers. That single illustration meant the difference between the user quickly grasping the application and the user floundering around for days and days, trying to build up that same concept from bits and pieces of information scattered about the application and manual.

Any time you learn a new piece of software, you go through the process of constructing a mental model of the software, what Don Norman calls the "User Model." Building a model requires a framework, and the framework consists of these large, key concepts. Without a framework, it is extremely difficult to learn.

The designers gradually work toward these concepts as they experiment with the program. Because of this, they have often internalized the concepts so thoroughly that they may not even be consciously aware of them. That's why manuals written from specs are usually impossible to learn from. The key concepts are entirely absent, so the user has nothing upon which to hang the bits and pieces of knowledge offered. Instead, they kind of float around in a cloud until the poor reader finally sees the pattern.

When a user does finally "get it," the bits and pieces do not then suddenly coalesce; that's not the way our memory works. Most of the bits and pieces, with nothing to hang themselves on, will have drifted off forever. The user must now re-read the entire manual, finally tying the bits and pieces in place on their new-found framework.

Manual writers will not themselves "get it" when they first start hammering on a new application. And I've even read manuals where the writer never did get it, either through lack of trying, lack of interest, or serious lack of ability. These manuals are useless.

Manual writers must be introspective. They must be aware as the "aha!" experiences that signal an incoming concept. They must then write that concept down and present it early enough to their readers that the readers don't have to go through the same struggle. That is the very essence of manual writing.

The job becomes doubly difficult when you have already internalized the concepts, either because you are a member of the development team or are already thoroughly familiar with the application. That is another reason I was so impressed with Pogue's Conflict Catcher 8 manual, because I happen to know David entered the project with way too much foreknowledge to experience any "aha"s at all. It requires a consummate writer to be able to distill and present the key concepts under such conditions.

4) Give 'em more than they deserve

Manuals need to cover the task domain, not just the operation of the program. That doesn't mean that a tax planner manual needs to cover the entirety of tax law. The depth and extent of the task domain that must be presented will depend on a number of factors, including the expected domain knowledge of the users and the amount of knowledge necessary for people to be able to use the application.

Expected knowledge of users

Writers (and marketers) tend to underestimate this. One of the great miracles of personal computers is that they offer a path for people to increase their knowledge and skill on their own. Extremely complex "professional" applications, such as Adobe Photoshop, have millions of users who never set foot in a design class. They have learned from their peers, they have learned on their own, and they have learned from reading the excellent Photoshop manuals. Write a manual that excludes everyone but existing experts and you will seriously impact your volume of sales.

Amount of domain knowledge necessary to use the application

Conflict Catcher is a fairly simple application designed to act upon and maintain the most complex and invisible part of the Macintosh OS. The folks at Casady & Greene realized this early-on and have always offered a pair of products, boxed together, to deal with it. One of those products is the Conflict Catcher application. The other is the manual. Each is a valuable and vital tool for the Macintosh user. Together they are even better.

Perhaps 75% of the Conflict Catcher manual is devoted to an in-depth explanation of how Macintosh extensions work. True, it would be difficult for the user to apply Conflict Catcher in the absence of such knowledge, but I've seen a lot of companies, faced with a similarly obvious need, completely ignore it.

The depth and extent of this domain knowledge presented in Conflict Catcher is impressive. Conflict Catcher users, having absorbed this manual, are fully able to maintain and repair their system extensions without the Conflict Catcher application at all! It is just slower and more tedious.

5) Make it enjoyable to read

One key concept, centered on what Macintosh extensions are and why they cause trouble, underlies all of Conflict Catcher. Let's see how two different writers present it:

From the Conflict Catcher 4 manual:

Since you first began using your Macintosh, you've probably extended the services that it provides on more than one occasion to keep pace with your changing needs….All these seemingly unrelated changes have one important thing in common—the addition of specialized files to your system to make new services available….This growth has created…the need to be able to troubleshoot problems they can cause by interacting with one another or other parts of the system.

This is clear and competent, but consider David Pogue's introduction, in the Conflict Catcher 8 manual, of the same concept:

"Your Mac's software is the result of an accidental collaboration among hundreds of programmers."

Now, that's great writing.

In Conflict Catcher, the process of discovering a bad extension is a collaboration between the application and the user, with the application carrying out a series of experiments and the user reporting the results. In version 4, the manual carried this warning:

"It's extremely important to answer this question accurately, so, if there's any doubt in your mind, repeat the test and double check—it does't take much extra time and it ensures that the results of your test will be accurate.

David Pogue's handling:

"If, when Conflict Catcher asks you whether or not the problem is still around, you deliberately lie, then you deserve what you get. But, if you answered the question incorrectly by accident, keep in mind you can "rewind" the conflict test without having to start over. Just…."

Both give you the information you need. David's is bedtime reading. The earlier manual is not.

Guidelines Summary

For the perfect manual, follow one of these two procedures:

A) If you are a writer, write your manual using the following methodology:

1) Supply a (real) manual.
2) Explain the problem being solved
3) Present the concepts, not just the features.
4) Give 'em more than they deserve
5) Make it enjoyable to read

B) If you need to hire a writer, hire David Pogue

A few substitutes do exist. Look through the supplemental manuals for sale in the book stores. Find out who among the authors can write. Contact them and offer them immense sums of money. It will be a good investment.

If you are hiring full-time writers, ask for samples of their non-technical writing, as well as their technical writing. It has been my experience that real writers write because they are compelled to, not because they are being paid. Most technical writers who have never otherwise written cannot otherwise write. (I'm sure exceptions exist.)

Actually read what they supply in the way of technical writing samples. Can you understand it? If not, why not? Is it because it is covering an area so complex and so arcane that you, a mere mortal, could not be expected to understand it? Or is it because the writer just regurgitated specs, instead of exposing the concepts and taking on the tough job of really training the users?

Superb writers are out there. They can be found. There are no excuses.

Response

Here are some points I would add to yours:

Writing is about Thinking
The real story behind powerful writing is not the choice of words, but the formation of thoughts. This is the difference between David Pogue1s elegant prose and what went before. We may call it great writing. It is in fact great thinking. To achieve any trajectory, words must reflect value-added thought.

The Manual as a First Date
You can show up dishevelled and decline to respond to polite questioning (like FrameMaker1s on-line help). And there will be people who still persist in the search for your inner beauty. But it is not the way to bet. Once upon a time, Microsoft put considerable effort into its making its manuals a source of competitive advantage. It still shows, though less than before. There may be a message here.

Manuals Can Sell Products
The classic case in my view is Hewlett Packard1s 12C calculator in the finance industry. The 12C was a superb product, but it had a problem: nothing is less intuitive than RPN logic. The 12C's power was accessible solely through its manuals, and these were superb. They were tutorials worthy of the name—lucid, courteous, but never lightweight. Great instructional material. Which brings me to my next point.

Technical Writers are Not in the Technical Business Technical writers are in the education business. There is more than something for them to learn from other educational material, especially in how complexity is unravelled. Of course, a technical writer has to know a bit from a byte, and a lot more. The most common misconception is that technical writing is a descriptive, mechanical process. In reality the core function is to teach.

Kind regards,
Barry Martyn

Excellent points all. I had left out the dimension of writer-as-teacher, and it is an important one.

Additional Responses

I agree entirely with your general assessment of user manuals in How to Publish a Great User Manual. However, I disagree with your recommendations for finding good technical writers on the following points:

TOG: "Look through the supplemental manuals for sale in the book stores. Find out who among the authors can write."

ME: Years of experience and lots of money wasted on commercially produced books have shown me that most of them perform very poorly. A truly useful, well-written software book is rare, even from authors who are highly recognized in the press.

TOG: "It has been my experience that real writers write because they are compelled to, not because they are being paid. Most technical writers who have never otherwise written cannot otherwise write. (I'm sure exceptions exist.)"

ME: Technical communication is not primarily about writing. It's about teaching and communication. It's not about telling a story or expressing your thoughts or feelings. Organization, layout, simplifying complex concepts, explaining why and how to do things, and identifying with users on their own terms are much more important than finesse with language. Knowledge of the English language is no more a primary indicator of a good tech writer than knowledge of C++ statements and syntax are primary indicators of a good programmer. Of course knowledge of the fundamentals is required, but applying the fundamentals to produce a usable work is an entirely different matter in both professions.

I've been in the business of technical communication for more than 24 years. I've won awards from peers and acclaim from users. I've hired writers and managed their work. One thing I can assure you is that people who think of themselves primarily as writers and who write literary or even marketing types of works usually are very poor at developing usable user guides. I've grown many gray hairs trying to work with "writers" who can't understand the tasks users are trying to perform, who can't understand the technicalities of the software tools they are writing about, and who can't explain or teach concepts and procedures to others. But they can write beautiful poetry, short stories, and essays! (I'll guarantee you that the samples of poor writing you provide in your article were written by English-major, literary types of people.)

The best technical communicator is a techy person who has the rare ability to communicate and teach through indirect means such as paper and online media.

Tom

The O'Reilly book on Frontier, by Matt Neuberg, is as close as I've ever
come to a book on computers which could be could be considered literature.

Luke Tymowski



I was quite impressed with your article, "How to Publish a Great User Manual". It was refreshing to read; I almost wanted to put on some jammies and cuddle up in bed with it. ;) *just kidding*

Anyway, this is the first time I've ever seen the "ASK TOG" web site. I have already bookmarked it. As a technical writer for a software company, I salute you and thank you for providing such a great web site. Keep up the good work!

- Tommy

I enjoyed your article about David Pogue's Conflict Catcher 8 manual. I used to edit Pogue's work for IDG Books; I agree, the man's a natural.

jim grey

As a longtime Windows WinHelp developer, I agree with you 100% on your observations in How to Publish a Great User Manual.

I am a connoisseur of fine manuals and online help. Extensis Corporation, makers of the finest Photoshop plugin filters, produces consistently fantastic manuals. I rely on their PDF manuals because I typically buy software for immediate download from the Net. Have never experienced a moment of trouble with Extensis PDF manuals. Their hardcopy manuals are also excellent.

Although not a vendor's manual, I found the IDG book TEACH YOURSELF ACCESS 97 VISUALLY to be the most stunning and superbly simple product guide I've ever seen. Check out ISBN 0-7065-6026-3. It is a visual delight which clearly delineates topics into understandable components. I purchased my copy at Borders booksellers and don't regret a dime of the expenditure. I only wish Microsoft had included the guide in my Access 97 application package.

Take care.

Roy Anderson

I found your article, "How to Publish a Great User Manual," to be a bit naive and amusing in its simplification of a profession.

As a broadly and variously experienced technical writer familiar with not only the profession, but also the history of and research in the area of technical writing, please understand that:

I offer no apologies, explanations, or excuses for American attitudes toward technical documentation. I'm inclined to resort to hasty (albeit likely accurate) generalizations about how our culture is, for the most part, intellectually lazy, impatient, and mired in a slovenly desire for both entertainment and instant gratification.

I strongly suspect that an American appropriately coined the phrase, "If all else fails, read the manual."

To pontificate, "If you are a writer, write your manual using the following methodology" is both arrogant and ignorant. Conversely, if you, Tog, are a technical writer, feel free to argue the merits of tech-writing methodology; otherwise, either do your research or state your opinions as being just that.

Consider that effective technical writing is an art unto itself, an art based upon grammar, style, consistent terminology, clarity, concision, factual accuracy, information mapping, layout and design (including fonts, indents, point sizes, illustration specifications and locations, table designs, and more), sentence length, translation concerns (increasingly important in this age of the Global Economy, European Community, and ISO 9001), documentation- and illustration-software selections, usability testing, spell checking, editing, proofreading, subject-matter-expert reviews, document validation (testing the manual against the actual product), indexing, resource scheduling and deadlines relative to product-release dates, print-vendor details, and myriad other facets.

Clearly, technical writing is not five simple concerns, as you would lead your readers to believe.

The world is full of lousy writing from would-be writers. Bad writing, in all forms, results in little more than wasted words, wasted time, wasted paper, and wasted money.

In my humble opinion, those aspiring to write humor or fiction have no place in technical writing. Most of us in this profession believe that the reader's time is too valuable to waste with inane attempts at cute humor, wit, or lengthy, chatty exposition. Many tech writers prefer to define an audience and their expected knowledge base early on, then write to that audience.

To suggest that your readers hire some guy based upon "supplemental manuals for sale in the book stores" then "offer them immense sums of money" is unsound advice. For example, not all software technical writers are effective hardware technical writers, and vice-versa; the installation and maintenance for the electrical and mechanical features of an automated bacon-processing line in a major food-product manufacturer is a world apart from the GUI for the same product. No one writer is all things to all people.

I am a "captive," an in-house, full-time employee of a company that does not specialize in technical writing. I consider myself to be, and have been told time and again that I am, a highly effective technical writer. I am not a freelancer, as many tech writers are; these one-man shows are known in the industry as "garage shops" in part because they lack the facilities (UNIX, Mac, and PC platforms running FrameMaker, Adobe Illustrator, Corel Draw, InterLeaf, Photoshop, etc., etc.) to meet the needs of a broad spectrum of clients. Previously, I worked in a technical-writing firm through which other companies contracted me to consult and write their manuals. Generally, these firms are a better, faster, and more efficient, reliable and frugal route than simply calling some guy who freelances or wrote a book .

To suggest that "real writers write because they are compelled to, not because they are being paid" is not entirely true. A journalist by degree, I fled the angry threats (from those whose names end up in unsavory stories) and low pay in part for the gentler, more lucrative vocation that is tech writing, and in part because I have a strong mechanical aptitude and a stronger knack for tech writing. I am not "compelled" to write technical manuals; these documents are anything but compelling. Fiction, and inventing it, is compelling. Journalism, and writing news, is compelling. Technical writing is supposed to be dull in part because we do not tell a story; we simply and concisely describe how to complete tasks. Our audiences need fast information to achieve a means to an end. They do not expect to be entertained. They do not expect to find a plot or a happy ending. They expect accurate and concise information easily accessible through such simple tools as comprehensive indices, and intuitive information order and design. Our employers' budgets do not wish to pay to print any more pages of paper than are absolutely necessary.

I hope I have instilled in you the complexities of a profession that is just now coming into its own as a respected profession. While I applaud your attempt at writing a "how to" article, I pity you the verbal assaults you may likely endure from the very artisans of the skill you attempt to define. As a former journalist and a long-time tech writer, I strongly recommend, as Mark Twain once said, that you "get your facts first, then distort them as you please."

Good luck,

Mark Forseth

Strangely enough, this was the only verbal assault I received.

 


Don't miss the next action-packed column!
Receive a brief notice when new columns are posted by sending a blank email to asktoglist-subscribe@yahoogroups.com.

return to top
---
 
Contact Us:  Bruce Tognazzini
 
Copyright Bruce Tognazzini.  All Rights Reserved