User Documentation

Unlike code documents, user documents are usually far divorced from the source code of the program, and instead simply describe how it is used.

In the case of a software library, the code documents and user documents could be effectively equivalent and are worth conjoining, but for a general application this is not often true. On the other hand, the Lisp machine grew out of a tradition in which every piece of code had an attached documentation string. In combination with strong search capabilities (based on a Unix-like apropos command), and online sources, Lispm users could look up documentation and paste the associated function directly into their own code. This level of ease of use is unheard of in putatively more modern systems.

Typically, the user documentation describes each feature of the program, and the various steps required to invoke it. A good user document can also go so far as to provide thorough troubleshooting assistance. It is very important for user documents to not be confusing, and for them to be up to date. User documents need not be organized in any particular way, but it is very important for them to have a thorough index. Consistency and simplicity are also very valuable. User documentation is considered to constitute a contract specifying what the software will do.

There are three broad ways in which user documentation can be organized. A tutorial approach is considered the most useful for a new user, in which they are guided through each step of accomplishing particular tasks. A thematic approach, where chapters or sections concentrate on one particular area of interest, is of more general use to an intermediate user. The final type of organizing principle is one in which commands or tasks are simply listed alphabetically, often via cross-referenced indices. This latter approach is of the greatest use to advanced users who know exactly what sort of information they are looking for. A common complaint among users regarding software documentation is that only one of these three approaches was taken to the near-exclusion of the other two

It is common to limit provided software documentation for personal computers to online help that give only reference information on commands or menu items. The job of tutoring new users or helping more experienced users get the most out of a program is left to private publishers, who are often given significant assistance by the software developer.

User Requirement Document

The user requirements document (URD) is used in software engineering.

An important and difficult step of designing a software product is determining what the customer actually wants it to do. What a customer informally says is desired may be incomplete, inaccurate and self-conflicting. The URD is meant to spell out exactly what the software must do and becomes part of the contractual agreement. A customer cannot demand features not in the URD without renegotiating and a developer cannot claim the product is ready if it does not meet an item of the URD.

The URD can be used as a guide to planning cost, timetables, milestones, testing, etc. The explicit nature of the URD allows customers to show it to various stakeholders to make sure all necessary features are described.

Formulating a URD requires negotiation to determine what is technically and economically feasible. Preparing a URD is one of those skills that lies between a science and an art, requiring both software technical skills and interpersonal skills.