Most Applications Needa User Manual

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

[DeleteWhenCooked: some consensus reasons why most applications need a user manual.]

Some observations:

In practice, attempts to eliminate user manuals usually fail. It is almost always necessary to provide some documentation.
UserInterfaces should be easy to figure out. Nobody should say "Well, sure, the UI makes no sense, but it will once they read the user manual."
Some people believe that "the UserInterface should be so simple that it does not require a user manual." This idea was popularized in the early days of the Macintosh. This idea 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 UserInterface as easy to figure out as possible, and ship a user manual, whether it's needed or not.
There are some manuals that are really valuable. When they are well written they make life as a programmer better.

Some questions:

Why is a good manual helpful?
What distinguishes a good manual from TheAlmightyThud?

Forces that encourage having a UserManual:

A 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.
Users sometimes get confused. A good user manual will help the user find what they need to know, and get back to work.
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.
Most user interfaces use an ambiguous short-hand.
- An abstract example: Does "opening" an object also "activate" the object?
- A concrete example: If 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?
Business reasons: It may be a "checklist item" (reviewers and/or customers may have a policy that it is required, whether it is functionally necessary or not; one's own company may have a similar policy about products shipped). It may add to an air of professionalism and/or getting value for one's money to ship one (or at least, detract from that if the manual is lacking).
Some actions are not reversible. For example:
- Network file deletion may be permanent.
- Disk defragmentation.
Most UserManuals have space to explain things, whereas most GraphicalUserInterfaces are crowded.
Good user manuals make proper use of English or other applicable human language. The language available to the manual writer is infinitely more powerful than the language available to the GUI designer.

Contrary forces (such as guaranteed reversible actions, and uncrowded GUIs) moved to UserManualIsAnAntiPattern.

Alternatives to User Manuals:

... ship a user manual, whether it's needed or not.

In general, I am in concurrence with this page, but I object to the above qualifier.

There are many situations where software falls short of the ideal and a user manual becomes the most efficient means to correct the shortcoming, at least at that time. If, however, the user manual is not needed, then do not spend the time, money, and resources to create, publish, and distribute a user manual. Ever read or even seen a user manual for a bank ATM or gas station POS (Point of Sale) terminal?

Yes, create a user manual when it makes sense to do so, but do not create one without need, and continue to improve software to eliminate the need.

I find that the best (most used) manuals are those walk users through common scenarios (UseCase) of the domain. Start with simple scenarios and move up the complexity ladder. Describing specific buttons or options is usually best at the screen-level. In these cases, clicking a Help button or option that describes the options on the given screen and only the options on the given screen is sufficient. If somebody wants to translate this into a paper version for a formal "users manual", so be it, but few will bother reading it in my experience and not worth the cost.

Manuals that describe how to add, change, and delete (ACD) every last entity are dry and usually ignored, and thus are a waste of time. Perhaps describe the conventions for ACD rather than replicate the instructions for each entity/screen (if the scenarios are not sufficient to achieve this). The UI should make most ACD obvious anyhow. If they are not, then the app probably needs a rework. Of course there are usually a few exceptions for the tricky areas of a domain, but these can usually be covered via the scenario descriptions mentioned. In short:

Document common scenarios, starting simple to complex
Put specific screen-oriented help into the app instead of paper
Avoid documenting every Add, Change, and Delete operation for each entity/screen, except the tricky ones as scenarios (above).
If you need to document too much, then the UI may need a rework.

--top

It seems to me that if an application ActuallyDoesSomething?, the use will need a manual to explain how to use this application to do that task. PaulMurray

One often-overlooked but particularly helpful thing in a user manual is extensive domain and/or background information and/or designer's notes that ties into the use of the program. The reader learns about the domain as it applies to the program as well as vice-versa, how they can make best use of the program, and what problems it was or wasn't intended to solve. This contrasts to a reader skimming over boring detailed manuals that tell step-by-step how to do things that the reader doesn't even know that they might need to do.

As an example, one may, for years, use just a few of the many features of a complex paint program laboriously editing images. Then switch to another one with fewer features, but which has a manual actually explaining why those features are there, how they can help and what can be done with them (instead of just how to use the UI to control them). The user may become much more productive and produce better results, using features that they never knew they needed. The software may be theoretically inferior due to fewer features, but in reality it is superior since it does a better job of solving the problem.

If the software could use added value or a competitive edge, it might need a manual.

See: UserManual, UserManualIsAnAntiPattern

CategoryDocumentation