Back

User and technical documentation

There are two types of documentation that need to be produced. These are User Documentation and Technical Documentation.

User documentation
With any product, some help needs to be provided for the users to enable them to run the software successfully. With many applications, those facilities are provided as software, as part of the application. To access the on-screen help, a user might click on a Help icon or press a function key, for example. A pop-up screen would then appear. A typical set of help features in an on-screen help system include:

    • An index to allow a user to scroll through help files.
    • A search engine to allow a user to type in key words or use natural language to search for solutions.
    • A FAQ (Frequently Asked Questions) facility so that users can find answers to common questions quickly.
    • Internet links to helpful web sites and support groups so that a user can find further help if they need to.
    • Tutorials, to show users how to carry out tasks. These are often animated and interactive.
    • Examples to help a user, such as a typical way to construct a formula.
    • Provision of a README file to tell the user important information before they get started using the product e.g. licence information.

A contact email address, so the user can report problems, get further help and so on.

Paper-based manuals are still fairly common. A typical set of features include a contents page and an index, to help users find what they want and annotated diagrams and writing, to explain how to use the functions within the software. This might include how to enter data, print out copies, get on-screen help, for example. There might be examples, to show the user how to do typical things, such as writing formulas. There could be a 'Getting Started Guide' in addition to an on-screen guide. The Getting Started Guide show users how to load up the software and configure it to their system. This might include extra instructions on how to configure the software for a network. There might be a ‘How to get further help’ guide, who to contact. There could be a 'Trouble-shooting Guide' for common problems, a description of the licensing agreement for the user and an explanation of the user's right to make a backup copy of the software.

It is important to remember that users are not usually technical experts so the language and presentation of the user documentation must be aimed appropriately.

Technical documentation
The purpose of the technical documentation is to describe how the system actually functions. It is not written with a user in mind, but to assist a technical person in the future. The technical documentation is needed by a technical person because all software has a 'shelf-life'. Just because it is 'finished' at a particular point in time, it doesn't mean that it will never need to be re-visited again for ‘maintenance’, to upgrade the software, for example. Maintenance is discussed in more detail in another section. Just as it would be difficult to maintain a car without the technical manual, so it would be difficult to work on software in the future without the technical documentation for the software. The person making any changes to some software may have had nothing to do with the original software product so needs some help finding their way around. 

Apart from a contents page and index, the technical documentation would typically contain:

    • the Requirements Specification
    • the hardware and software specification
    • all of the documents from the design specification, including any program specifications and how to configure the system
    • details of all of the tests that were carried out and the results of the tests.
    • the code for any new software that was written. This should be fully documented so that someone can follow how the software works. 
    • the tables that detail what names have been used for variables, constants, subroutines and data structures in the code
    • a map of the whole software product so people can find their way around it easily. Imagine wondering where to start if you were given the task to modify in some way a program that was a million lines long!

This is a technical document. It is expected that appropriate jargon and technical diagrams would be used, although it still needs to read well and be easily understood by other technical people.

Back