Lecture 16 - Documentation

What is Documentation?

The printed or online documents that explain things: identify the parts of your hardware or software, give installation instructions, and give directions for use. In programming this includes explanations of the code

"What the logic is, why it is written that way, what the code is doing"

Documentation is needed for the following purposes.

• As a mode of communication
• To support the project management activities
• System maintenance

When documenting information a standard format should be adopted, they should provide simple, comprehensive & unambiguous set of information.

Attributes of Good documentation

1. During the various stages of a project development such as Systems analysis, Systems design etc the need arises to pass on information. Sometimes this is done verbally, but this is short term & subject to loss or misses interpretation.
2. Documents are better, but need to confirm to rules to avoid ambiguity, duplication, omission & contradiction.
3. Good standards provide a framework & are not meant to reject rules. Often they are provided in the form of checklists.
4. Standards need to govern the way the documents are prepared & maintained.
5. Good documentation requires time and effort and an application of who the audience will be for such documentation because that will dictate the style & tone of the work.
6. However do not create unnecessary documentation, be selective and consider if the output is really needed.

The primary outputs of good documentation are:

• Complete and up to date
• Well structured
• Indexed
• Presented in a standard form

Types of Documentation

• User Documentation
• System Documentation
• Program Documentation

User Documentation
This will describe the functions of the system without referring to how they are implemented. The user documentation will mainly consist of users requests. This will include the following.

• State the problems - Definition of the organization, the actual problem will be stated.
• Assess the feasibility - This is the description of the proposed approach to the project which states the objectives
• Plan the schedule for lmplementation - This will be a time table for the development work. lt will also state an approximate completion date of the project.

System Documentation
The system documentation describes the system functions and how they are implemented. Most system documentation is prepared during the system analysis and system design phases.

System documentation consist of;

• Data dictionaries
• Data flow diagrams
• Object models
• Screen layouts
• Source documents
• Initial System requests

Program Documentation
The program documentation will consists of more detail description of the modules and continues during the system implementation It begins in the system analysis phase and continues during system implementation includes process descriptions and report layouts.

Programmers provide documentation with comments to make it easier to understand and maintain the program. An analyst must verify that program documentation is accurate and complete.

The documentation required to enable a programmer to maintain a program over its life may be divided in to two:

1. Internal Documentation
2. External Documentation

Internal Documentation
This covers the aspects of programs which are embodied in the syntax of the programming. These includes:

• Meaningful names used to describe data items and procedures.
• Comments relating to the function of the program as a whole and of the modules comprising the program
• Clarity of the style and format - one instruction per line, indention or related groups of instruction, blank lines separating modules.
• Use of symbolic names instead of constants or literals in the procedural code.
• Develop the program as set of modules

External Documentation
The category covers the supporting documentation which should be maintained in a manual accompanying every program. It is essential that as changes are made to a program, it's external Documentation rs updated at the same time. Out-of-date documentation can be misleading to a maintenance programmer and result in much time being wasted.

External Documentation should includes;

• A current of the source program - the program as written by the programmer, including any memory maps, cross references, and so on, that are able to be obtained from the compilation process.
• The program specification - the document defining the purpose and mode of operation of the program
• An explanation of any formulae or complex calculations in the program
• A specification of the data being processed - data accepted from of displayed on a screen, items in reports, external files processed, including the format of record structures and fields within those records. All data being describe in terms of its size, format, type and structure.
• Program Specification
• Analysis Information
• Program Design
• Design Checking Methods
• Program Code
• Test data and test outputs
• Testing methods
• Review Documents
• Detail description of the program
• Any special details required for programing such as formulas and calculations
• Hardware and software requirements
• User interface and their structures