Documentation in the systems life cycle

We have seen that the Requirements Specification is the agreement between the company buying a solution and the company building it. We know that it details what the system will do and the standards by which the items in the Requirements Specification will be judged. We also know that it is a key document used in the evaluation once the product has been built.

The design documentation details how the solution will be built. It includes written descriptions of how the system will be designed so that it can do all of the things set out in the Requirements Specification. It includes diagrammatic representations of some of these descriptions, other diagrams that help the design of the system, a data dictionary, input and output designs and a program specification. The design documentation itself needs to be detailed enough so that it can be given to anyone skilled in building systems and they will be able to design the product from the information given to them. Part of the design documentation is the program specification. This specifies what programming language to use if appropriate and details what functions the program code needs to perform. Algorithms could be used to describe these functions or diagrams such as flowcharts or Jackson diagrams could be used.

User documentation

User documentation can come as on-screen help (that comes with the software), online help (where the guide is on the Internet) and a paper-based manual.

On-screen help

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 an icon or press a function key, for example. A pop-up screen would then appear. A typical set of help features of 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 to problems.
  • A FAQ (Frequently Asked Questions) facility so that users can find answers to the most commonly-asked 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.

Internet-based help

Because Internet speeds and bandwidth have increased, many software products now have an online user guide rather than an on-screen one, and sometimes a product may have both on-screen and online. Online help guides can be easily updated, corrected, modified and added to because the company only has to do this on one copy held on their web server. This is good for a user, assuming they have a good Internet connection, which may not always be the case.

Paper-based help

Paper-based manuals are still common. A typical set of features include:

  • A contents page and an index, to help users find what they want.
  • 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.
  • Examples, to show the user how to do typical things, such as writing formulas.
  • A 'Getting Started Guide', to 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.
  • How to get further help, who to contact.
  • A 'Trouble-shooting Guide', to explain how to deal with common problems.
  • A description of the licensing agreement for the user.
  • An explanation of the user's right to make a back-up copy of the software.

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 software has a 'shelf-life'. Just because it is 'finished', doesn't mean that it will never need to be re-visited again for 'maintenance'. Maintenance is discussed shortly. 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 technical documentation will typically contain:

  • The Requirements Specification.
  • The hardware and software specification.
  • All of the documents from the Design specification, including any program specifications.
  • How to configure the system for different computer set-ups.

Business | Systems

QR Code
QR Code different_types_of_documentation (generated for current page)