User Manual Is Anti Pattern

In WriteTheUserManualFirst some say that a well-designed application doesn't need a manual. The context of WriteTheUserManualFirst says that the customer requires one, so in that context there is no question of not producing one. It begs the question, should an application have a UserManual?

Yes, if the user has a use for one. Next question!

The original statements follow:

An AntiPattern: A well-designed application doesn't need a user manual, in the same way that good code doesn't need comments.

When a user needs to check a manual, the user interface has confused the user. [See Note 1]
The user manual of a well-designed application conveys no new information ("The open command causes the selected object to be opened"). [See Note 2]
Or the user manual can provide context, instead of trivial definitions. For example, the user manual can explain when (or why) the user would want to open an object. In a very well-designed application, the context is also obvious within the application.

[DeleteWhenCooked: Is enough of this section included in UserManualIsAnAntiPattern and MostApplicationsNeedaUserManual that this section can be deleted? -- JasperPaulsen]

Oops. The topic sentence was too terse, so many people misinterpreted it.

The alleged pattern is: "A well-designed application doesn't need a user manual, in the same way that good code doesn't need comments."

It is an anti-pattern to omit the user manual, because (in practice) it is almost always necessary to provide some user documentation.

Perhaps it should have read:

Some people believe that "A well-designed application doesn't need a user manual, in the same way that good code doesn't need comments." This belief is an AntiPattern, when applied to entire applications. In practice, attempts to eliminate user manuals usually fail. It is almost always necessary to provide some documentation.

On the other hand, this belief can be helpful at the feature level. If you can design a feature so that the user easily understands what it is for, how to reach it, and how to use it, then the UserInterface may be all the documentation you need for the feature.

[I think that where this idea started was the notion that UIs should be easy to figure out, and one shouldn't say "well, sure, the UI makes no sense, but it will once they read the user manual." In reaction to that was the idea (popularized in the early days of the Macintosh) that, instead, the UI should be so simple that it didn't require a user manual.]

[That is a good thing to aim for, but it's not the same thing as saying "...and therefore we won't ship a user manual." Make the UI as easy to figure out as possible, and ship a user manual, whether it's needed or not.]

Inapplicable Domains There are domains where the idea of a self-describing and automatically intelligible UI is just a gratuitous utopia. Many claims, such as that "good code" does not need comments, often are viewed as an attempt to justify the omission of tasks that are customarily considered to be necessary, but some programmers find distasteful. A similar claim could be made about UnitTests ("UnitTests are an AntiPattern; as good code doesn't need them") and it would be just as wrong. See IntentionalRedundancyDoesNotViolateOnceAndOnlyOnce

Examples: Try to use an Unix environment without its man pages. Try to convey the options provided by command line through means of GUI manipulation of screen objects, that should be also self describing. Come back in a decade or so to let us know how it went.

There are domains for which the idea of a GUI as easy to figure out as possible is nonsensical. See Dijkstra's famous quote: a formula is worth a thousand pictures. Try to use Mathematica, Autocad, LaTex, or any other application that is more complex than an address book. Heck, your average user can't even begin to use Excel without a proper user manual in the form of online help, tutorials. And let me see the guy who can create non-trivial Excel applications or templates without using the help system.

[DeleteWhenCooked: Is the summary of this section in MostApplicationsNeedaUserManual good enough that this section can be deleted? -- JasperPaulsen]

Take as an example the Query Analyzer that ships with Microsoft SQL Server. This executes SQL statements against a database. I can see that explaining in detail the menu commands to open a query file or select a database might not be very valuable. I use this tool quite a bit at work. I never had to read about how to use the Exit command or the Search menu, so that part of the manual was wasted on me.

I spend a lot of time reading the "Book On Line" (BOL) which explains in great detail how to use the Transact SQL dialect. BOL is a reference guide. I can't think of how that information could be presented to me if it weren't in the form of a manual, in this case, an electronic hypertext.

Maybe this kind of document isn't what you meant by "UserManual" but I included it in my definition. This adds a new wrinkle. Is "UserManual" the wrong word to describe this kind of document, and do I confuse the issue when I include things like a language reference in the discussion? Is "UserDocuments?" a better word?

[Microsoft's SQL Server "Books On Line" is a UserManual for SQL Server's SQL interface. It is not a complete UserManual for the various tools that are bundled with SQL Server, such as EnterpriseManager? and QueryAnalyzer?. "Books On Line" answers the "what do I want to type" questions, not the "where do I type it" questions.]

When people say that UserManualIsAntiPattern, they're talking about user manuals for GUIs. A programming language is a horse of a different color, and definitely does need manuals, regardless of what they're called. But as a matter of terminology, I think that there's a big difference between a "user manual" and a "reference manual"/"reference guide".

Similarly my car shouldn't need a "user manual" just to tell me how to steer it and change gears, but I still need some kind of documentation to tell me what kinds of oil and tires it needs, etc. It confuses the issue to lump all documentation together under the single name "user manual".

Actually, most cars do have an "owner's manual". Typically, it is about 200 half-pages long. Most car owner's manuals explain how to steer, change gears, and use the radio (often a separate manual even longer than the one for the car itself). It also gives some simple maintenance details, like what kinds of oil and tires it needs. Most car owner's manuals do not explain complicated maintenance details, like how to replace the CV joints. That is usually left to a repair manual. Also, a car owner's manual does not teach the user how to drive, nor does it explain the traffic laws. It just points out (to someone who already knows how to drive) how to drive this car. (And maybe points out the car's blind spots.)

So in short, the need for this BOL reference guide to Transact SQL is a red herring; it has nothing to do with user manual patterns/antipatterns.

What damage do I do to the discussion, do you think then, if I replace all occurrences of UserManual with UserDocuments??

I fail to see that such a change is motivated by the current discussion. There's a difference between a user manual addressing UI issues, and a reference manual addressing deeper non-UI issues, and there are other possible types of documentation as well, such as tutorials, strategy guides for games, cheat guides for games, marketing guides for OEMs, etc etc etc.

I don't know what the phrase "user documents" means, exactly. Any and all documents for users, including the warranty papers???

Yes, the entire suite of books, references, getting started guides, graphs, glossaries, and yes, even warranties, that are delivered with the executable to the user, as opposed to the UML diagrams, design specs, performance tests, functional specification documents, and internal memos we don't intend to deliver to the customer. All the documents that are delivered to a user are "user documents" in my mind. If I am writing a warranty, then I must have some understanding of what I warrant the software will do. That's useful information, and would direct, in some small part, the character of the program I write. That's what I was thinking through all this. It is for the user, and is often delivered as a manual. If that's not what everybody else was thinking, rather the User Guide that lists all the buttons on an application, then I can understand why there would be resistance to placing much investment in that little piece. That's what motivates my suggestion that I'm using the wrong word.

Well, I guess it'd help avoid misunderstandings and unnecessary arguments were you to carefully define such terms, then, so at least people don't think you mean A when you actually mean B.

I tried. I wrote in the UserManual page what I meant and I summarized the definition again in WriteTheUserManualFirst. Once again I am confronted with the fact that we humans bring with us assumptions of meaning that mere formal definitions can't easily change. No wonder I've felt so many ZenSlaps during the course of this topic!

You've been more than understanding. This idiotic title, should in the end, be deleted. Every now and then, somebody with attitude comes to show off on wiki, and what better (and safer) way to show off than starting a "demolition derby style" page. It's been done again and again, on a close subject we've had ReplaceDocumentation. Saying X is crap, X is evil, X is an anti-pattern, doesn't engage the attacker, who typically is searching for validation of his own ego, lacks understanding, a broad culture and experience in the software field, all in all, initiators of pages like this are confused, and they project their misunderstanding and maybe lack of confidence and certainly lack of knowledge. -- CostinCozianu

I thought Skip himself was the one that created this page? (Not the same thing as saying that the title summarizes his own position, of course.)
Yes, it was I (SkipSailors) who perpetrated this topic. One of the counters in WriteTheUserManualFirst was that the UserManual is an AntiPattern. I felt a strong desire to get that idea out in the open where we could talk about it. It would have been easy to delete the irritating paragraph in WriteTheUserManualFirst but irritation is a sign that something needs worked out. I would hope that we can work it out here.
I have seen and, much to my unending shame, been a part of writing instruction manuals on software I've written that are nothing more that an inventory of buttons and menu commands adding nothing to the delivered product except TheAlmightyThud. There is enough of this kind of writing in the software business that calling a UserManual an AntiPattern is unsurprising. I am also not surprised that we tend to think sometimes that such inventories are the kind of documents we should expect to be written, and that we might as well not write them. There are some manuals, though, that are really valuable. When they are well written they make my life as a programmer better. I want to understand why a good manual is good. -- SkipSailors

A user manual can eliminate even the possibility of user confusion -- or so it is hoped. But why is the user manual immune to the problem of causing user confusion? Are programmers unable to communicate to users while manual writers can?

Programmers are not technical writers. Actually, they can barely write their way out of a wet paper bag -- let alone try to convey application operations to a neophyte user. This is a subject which has been done to death within this Wiki (just take a look through the CategoryDocumentation pages to see what we're talking about here). The programmer who creates the application is an expert in the craft of translating data and events into action and consequence. The professional writer who creates the manual is an expert in the craft of using words to describe the data, events, action, and consequences of all this. The two areas of expertise can't possibly be equated.

This begs the question. Why is the user manual immune to the problem of causing user confusion? Why should manual writers be any more communicative in their medium than programmers are in a programming medium?

Okay, somebody is obviously not doing his homework. Can we not agree that programmers and technical writers have different skill sets? Can we not agree that it is far more likely that a programmer will lack the skill to convey an operation to a user than a skilled technical writer? For that matter, do you want your dentist to give you a haircut, or your gardener fix your plumbing? Use the appropriate skills to solve the problem at hand.

Why should the technical writer have any more idea what user operations are required than the programmer? Is it not the responsibility of the user interface to convey this information back to the user? Why the presumption that the user interface is unclear and that a user manual provides clarity? From the analogy above, it would appear the technical writer would be the odd man out; being neither a user who understands the problem domain nor a programmer who understands the solution domain.

Good points. I've copied and refactored somewhat all this up to the top section, see "Inapplicable Domains" Since there were no objections to yesterday's refactoring and copying of text to the top of the page, I just deleted the original versions down here. DeleteWhenCooked

This page departs from the obviously flawed assumption that one can engineer the representation of non-trivial information as GUI objects, or alternatively that user manuals contain only trivial information (like in the straw man argument "The File->Open command opens a file").

This still begs the basic question. Why should the user manual writer be any more communicative that the program writer? Identifying poorly written user interfaces is not any more of a validation than citing poorly written user manuals. Both exist. It is also not sufficient to blindly state that it is an "obviously flawed assumption" that a user interface can be well designed. Why should the user manual writer be any more communicative that the program writer?

For a start, the user manual writer is only trying to communicate to the user, whereas the program writer is also (or only) trying to communicate to the computer. In addition, there can be a conflict between a user interface that is easy to use first time and one that is efficient or ergonomic to use time after time. Furthermore, it is usually easier for human beings to learn how to do things by being shown and/or told; figuring it out for themselves, no matter how obvious it is, is a very poor second (although learning this way is more thorough and lasting, so it has its place). In short: deciding what, if anything, should go into the user manual and other non-program artifacts is as much a design activity as any other division of responsibilities in software development. Do I hear SeparationOfConcerns?
In addition, the technical writer uses English (or other human language) as a means to convey information, whereas the programmer is bounded by GUI elements. So there's no question that right from the get go, a good technical writer can communicate much more to the end user, and communicate it more effectively. There can be tutorials, reference manuals, training manuals, different kinds of documentation suitable for different stages in the process of getting a user expert in using a software product.

Any response to the initial question beyond assertions that "there's no question that right from the get go"?

English, text, and language in general is difficult to use to express complex ideas, hence "Let me show you." Language is limited by its nature to generalization and serialization, where as programming allows the expression of details and supports parallel paths. The role of software is to express complex, detailed operations in more clarity than written documentation has ever been able to do. For user manuals, there is no reason to believe that a user manual writer would have more knowledge of what needs to be communicated to the user than the programmer who is actually doing the work.

Software is replacing written documentation at a surprising rate. There is no question that software has been and continues to be written that communicates poorly. The same can be said of written text. A great deal of software is used without reference to a user manual and users, quite correctly, will place the blame for lack of clarity on the software. There is little evidence that a user manual will eliminate user confusion.

Excuse me, but I qualify the above paragraph about English vs. GUI as handwaving, without a shred of supporting evidence. That software is more expressive than English, oh dear. And GUI can express complex ideas, wow, whereas English or other kind of language, cannot, really ??. This is simply ridiculous when presented as a general rule. If that was true, you wouldn't need programming languages to write programs into, you'd write them using GUI driven application builder with no text support, an idea known to have spectacularly failed. And just when software engineers thought they got a clue from electrical engineers peers and were moving to more and more "diagrammatic", "high-level", "visual" languages (UML, oh dear), their hardware colleagues were rediscovering the joy of proper languages. "Let me show you" may work just fine for buying gas and using an ATM, but we have software systems around that are just a little bit more complex than that.
Again, abundant examples were presented where user manual not only helps but is a stringent necessity and it was conjectured that all non-trivial software systems do need an user manual, but in defense of the opposite idea, we've got more handwaving. What's happening here ?
I'd have to agree with Costin. From whence comes the theory that "Software is replacing written documentation at a surprising rate"??
- What is the purpose of software but to automate manual operations? Why do we do it? Simply because the written documentation for how to do the task is insufficient. Why do we have graphical user interfaces? Because command lines (UNIX et al) even with written documentation were not sufficient, a software solution was required. In the U.S., why do products like Turbo Tax exist when free written documentation in the form of the 1040 instructions and numerous other related instruction booklets exist? Because they are not clear to the user. Again, software provides more clarity and detail than written documentation. When VCRs became too difficult to program, front end software was added; documentation failed to do the trick. Archtectural design rules have long been written, so why do we have software packages to do it? Because, the written text is far too complex.
- No, in each case that is not why. In short you are saying that we wouldn't need nor use software if only the written documentation were sufficient. That is absurdly wrong. To a first approximation we use software to do things that we couldn't do at all otherwise, for instance desktop publishing was impossible before typesetting software, and that had nothing to do with sufficiency of documentation of anything.
- In other cases software makes things easier that would still be possible, but slower or more complex or lower quality etc than if done manually, but that still has nothing to do with documentation.
- Lastly there are cases where the software does things that some particular user just doesn't know how to do, like maybe a difficult integration in Macsyma, but again documentation is irrelevant. It would be erroneous to claim that user ignorance of any and all topics is the same subject as documentation.
- And comparing GUI are a poor substitute for command line utilities for non-trivial interaction with the OS. You cannot handwave a problem's essential complexity by wrapping a GUI around it. There's a distinction between accidental complexity that can be removed by better software design including GUIs and essential complexity. Otherwise a cleverly design GUI would make programming a trivial task. Unlike your examples with ATM and filing tax returns, there are categories of software users (including but not limited to all engineering professions, architects, etc) that use software to resolve essentially complex problem in essentially complex domain. For that the software has to offer a non-trivial language of interaction, (examples like LaTex, AutoCad's AutoLisp, Unix command line, etc ), and you can't learn any of that stuff without good documentation, there's no GUI that makes a good substitute for non-trivial languages.
- And contrary to the allegation above, command lines are sufficient for non-dumbed down users. GUIs are only good for users with modest needs, but you cannot dumb down all the users to the level where a GUI is sufficient.
  - Indeed, a late friend of mine (Jim Joyce) ran a Unix-based business in the 1980s, and he literally hired 100% of his office staff from people he met in a park in San Francisco while walking his dog -- quite a colorful bunch of people -- who in every case were technically illiterate, and yet trained them to be successful users of the Unix shell, the vi editor, the nroff/troff typesetting system, to use the man command to refresh their memories on commands, and whatever other miscellaneous command line tools they needed to work for his business. And I worked closely with his staff, and saw this with my own eyes; I'm not relying on the stories he told. -- DougMerritt

There is a much better chance that a technical writer will be truly skilled in their use of language, than the chance that the GUI designer/implementor will be truly skilled in the art of doing effective GUIs. Both bad manuals and bad GUIs are frequent, but bad GUIs are far more common.

Therefore manuals can act as a safety net.

Again this is merely a return to the initial statement that technical writers are superior to programmers without justification of the statement. Even if that statement is true, it does not necessarily follow that written text is more clear than interactive software. What is the justification for this belief?

That's misinterpreting. Focus on "safety net" above.

Quite the no-win situation saying only poorly written applications need a manual. If you need a manual you are saying your application is poorly written. So all the books on all the software pretty much indicate that there is no well written software that does anything even marginally complex. This leads me to believe that using the well written test is useless.

Is this redundant? See comments at top of page. DeleteWhenCooked.

Notes:

The user may be confused, period. No amount of user interface refining can accommodate all users for eternity, and there is going to come a user who will misinterpret any term or description of an operation no matter what you do. Therefore, have a manual.
"The open command causes the selected object to be opened." Okay, but does "opening" include activation? For instance, if I click on a sound file do I just get the file opened for examination and possible editing, or does the sound play and then the application terminates? Perhaps opening the file causes the sound to play, but then it is automatically rewound to the beginning and I can now edit it? It's opened, isn't it?