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: Some questions:


Forces that encourage having a UserManual:

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:

--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

EditText of this page (last edited October 14, 2010) or FindPage with title or text search