User Manual Is An Anti Pattern

It has been suggested that the UserManualIsAnAntiPattern, but it seems that most people on this wiki think that MostApplicationsNeedaUserManual. [DeleteWhenCooked: These two pages are being carved out of UserManualIsAntiPattern.]

[DeleteWhenCooked: canonical AntiPattern form goes here.]

Context: (list moved to CharacteristicsOfaGoodUi)

Forces:

The forces that lead to TheSourceCodeIsTheDocumentation?
Users are curious -- they want to try things out.

Proposed solution:

Write a user-manual that:
- Basically restates the name of each feature.
- Possibly include how to reach each feature.
- Does not explain why a user should use a feature.

Resulting context:

The user manual is redundant
- "The open command causes the selected object to be opened."
The incentives to create a well-designed, user-friendly application are undermined.
- There is more room for fine print about the effects of commands,
- The context for commands can be moved out of the UserInterface into the manual.

Raw material:

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

I'd say that this right here is an anti-pattern I see all too often as a user. There are plenty of well-designed applications and systems that model complex problems and require documentation.

You are attempting to define a "good user interface". You can't. Doing so is beyond the state of the art. Each item you list below is reasonable from one point of view, but highly arguable from a different point of view, and there is no justification for why those are listed and not some other more important UI principles, and there is no definitive list in existence that you can copy. GUI design is still an art, it has not been reduced to engineering.

This is a can of worms. Just say "good intuitive user interface" or something.

(You might want to copy your list to a UI page, though, it's an interesting list in its own right).

(Please read each statement as saying: "Within this application, ..." . Other applications have different contexts, so this AntiPattern may not apply to them.)

Your answer doesn't have anything whatsoever to do with my comments. What I meant was "don't put that list there, it is not appropriate."

I sympathize, now that I see that you were reacting to comments made on another page, but still, you can't expect to successfully list the characteristics of a good UI under the Forces on this page, it'll be hard enough to come up with consensus on a separate page, so I created CharacteristicsOfaGoodUi for that.

Many instruction manuals on software 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 biz that calling a UserManual an AntiPattern is unsurprising. Sometimes we think that such inventories are the kind of documents we should expect to be written, and that we might as well not write them.

When a user needs to check a manual, the user interface has confused the user.

Again, my experience says the above comment is horribly wrong. Don't over generalize. Maybe you mean a simple business or word processing application should not require a manual? Or maybe you mean an application whose underlying principles, workflow, and patterns can be represented within the user interface and it's help system? The problem is with the way manuals are written, not with the concept of a manual itself. Have you ever bought a book on your favorite programming language/operating system?

The author of that comment didn't invent the concept, it is a claim that has been made very often in the industry.

Anyway, at its best, the claim means that, if you already know what you want to do, you should be able to figure out how to use the user interface to accomplish that without needing to refer to the manual. For instance, if I know I want to change the height/width of an image (either in inches or in pixels) in Photoshop, I'd better not have to read the user manual to find out how.

The much-vaunted Photoshop fails in this regard, btw. It is considered intuitive only because most people learn to want things from using Photoshop, so they never had to search for how to do that thing. Others who are already aware of the possible image manipulation algorithms that have been invented, and know that they're somewhere in Photoshop, can have a very hard time finding them.

Discussion: For the set of forces listed above, this is an AntiPattern. But there are other sets of forces, such that MostApplicationsNeedaUserManual.