Software Documentation – Understanding User Documentation


Unlike the literature on code, user documents are usually quite distant from the source code of the program, and simply describe how it is used.

In the case of a software library, documents on the code and user documents could be effectively coupled and it is worth to combine , but this is not always true for applications in general.

Lisp machines follow the tradition that each element has a field code documentation attached.

Online, users can search the Lisp documentation and understand their own code function.

Typically, the user documentation describes each feature of the program, and the steps necessary to operate. A good user document can also provide thorough online support. It is very important that users documents are not confused, and they are updated.

The user documents do not need to be structured in a particular way, but it is very important that they have a specific index. Consistency and simplicity are also two very valuable qualities.

There are three main ways of organizing user documentation:


A tutorial approach is most useful for a new user. In this method the user is guided through every step of performing specific tasks.


An intermediate user generally employs a thematic approach, in which the chapters or sections focus on a particular area of interest.

In the case of computers, it is common to limit the provision of software documentation to reference information on commands or menu lines.

Marketing materials

For many applications, it is necessary to have promotional materials to encourage casual users to spend more time to focus on the product.

This form of documentation has three objectives:

Inform the user about what exactly the product does, so that their expectations are in line with what they will receive.

Explain the position of this product compared to other alternatives.


About the Author