Why Documentation?
Documentation is needed because it is
- A means for transfer of knowledge and details about description of the system;
- To communicate among different teams of the software project;
- To help corporate audits and other requirements of the organization;
- To meet regulatory demand;
- Needed for IT infrastructure management and maintenance;
- Needed for migration to a new software platform.
Process of Documentation
The following are various steps involved in the process of documentation:
1. Collection of source material: The very first step of any documentation process is to acquire the required source material for the preparation of the document. The material is collected including specifications, formats, screen layouts, and report layouts. A copy of the operational software is helpful for preparing the documentation for the user.
2. Documentation Plan: The documenter is responsible for the preparation of a documentation plan, which specifies the details of the work to be carried out to prepare the document. It also defines and the target audience.
3. Review of Plan: The plan as set out in the process above is reviewed to see that material acquired
is correct and complete.
4. Creation of Document: The document is prepared with the help of document generator.
5. Testing of Document: The document created is tested for usability as required by the target audience.
6. Maintain Document: Once the document is created and distributed, it must be kept up to date with the new version of the software product. It must be ensured that the latest document is available to the user of the software.
Documentation Essentials
Characteristics of good documentation:
- Availability
- Objective
- Cross –referable
- Easy to maintain ✓ Completeness
Need for documentation:
(Purpose for documentation)
- Without proper documentation, effective communication of who, what, where and how of the system is difficult.
- Audit ability and control are difficult to achieve without documentation.
- If changes are made then it will not be clear to those who try to comprehend the system later on.
- While converting from one system to another system if there is no proper documentation, there will be chaos.
Documentation Methods
- It is desirable for the client and system analyst to work jointly in writing the request since each can contribute knowledge the other does not have.
- The written system’s request is merely a statement of the user’s problem.
- Documentation also includes plans to test the system and convert from the old to the new one.
- Anything written about the system is designed or a function is documentation.
Various documentation methods are
- System documentation
- Programming documentation
- Operation documentation
- User documentation
- Management documentation
- Training documentation
- Implementation plan
- Appendix
1. System Documentation:
It describes the overall design and includes a system flowchart, input/output formals, file descriptions, control requirements, report specifications, etc.
2. Programming documentation:
Programmer should insist on proper documentation before starting a job. This includes programming specifications, description of program logic including graphic aids such as program flowcharts. Design and program documentation are for the use of technical personnel.
3. Operations documentation:
Operation documentation is for those who will keep the system running from day today. It contains operating instructions for normal operations and directions for handling problems and breakdowns.
4. User documentation:
User documentation contains generally main two types of information; complete details to handle each case the system process and overall picture of the system so that they can see their role in the total operation of the company.
5. Management documentation:
Management documentation provides three kinds of information:
- Evaluation of progress on systems development
- Monitoring of existing system
- Objectives and methods of the new and existing system
6. Training documentation:
It includes the user training manuals and materials to be used in the system conversion and installation of new system.
7. Implementation plan:
Implementation plan and result of implementation must be documented.
8. Appendix:
It contains all other information like feasibility study report, problem definition, summary of general information, etc.
Developer and User Manuals
User Manual :- It provides a vehicle of communication between customer and developer. It is prepared using information from the system definition as well as the results of prototype studies and mock-ups of user displays and reports.
User manual should contain
- System Object
- Related System
- Responsibility
- Cost benefit analysis
- Data flow diagram
- Operating procedure
- File layout
- Report layout
- Validation parameter
- System about system
Review & monitoring Of Execution
The review team prepares a formal plan around the objectives of the review, the type of evaluation to be carried out and the time schedule required. An overall plan covers following areas:
1. Administrative plan:
It reviews area objective, operating cost, actual operating performance and benefits.
2. Personnel requirements plan:
Under this plan, all activities involving system personnel and staff members associated with the system are evaluated.
3. Hardware plan:
The main target of this plan is a comparison of current performance specifications with the design specifications. It also points to necessary modifications to be made.
4. Documentation review plan:
The objective of the review plan is to evaluate the accuracy and completeness of the documentation compiled to date and to its conformity with documentation standards established earlier.
Application Change Management
Change management is the process of planning and coordinating the implementation of all changes
Change management objective:
- To minimize the adverse impact of necessary changes on system integrity, security and the service level agreements.
- To allow the coordination and planning of changes in order to provide a stable production environment.
- To maximize the productivity of the persons involved in the planning, coordinating and implement of quality changes.
Change management mission:
- To ensure the documentation of all proposed changes prior to installation ✓ To ensure verification of technical completeness.
- To ensure that the timing of change execution does not conflict with the business cycles or priorities.
- To ensure appropriate management involvement and approval.
- To ensure the verification of successful testing.
- To ensure the documentation of actual change installations and/or change back outs.
Change management guidelines:
- All changes in the system must be monitored and controlled.
- Change is the normal mode of operation, not the execution.
- One change management system must be in place.
- A change coordination function must be established to control the day today activities of change management system.
Types of system maintenance
There are four types of systems maintenance.
- Adaptive maintenance
- Corrective maintenance
- Perfective maintenance
- Preventive maintenance
Adaptive Maintenance:
- It begins with the request for service from the user. Then it is assessed by the committee. Once approved, it goes to the maintenance programmers who treat this as a mini system development assignment.
- It also includes housekeeping tasks like back up of files, file copying, file conversion, etc.
Corrective Maintenance:
This is performed in response to software failure. The errors that occur can be classified as:
- Program logic error : data type error, incomplete logical paths
- System error : hardware problem or software design problem
- Operation error : loading incorrect files, improper back up of computer files
- User error : deficiencies in training demonstration and user guide
Perfective Maintenance:
- It is performed to improve or maintain the program’s efficiency.
- There are some ways to improve system performance :
- Modifying program data structure
- Eliminate temporary files which will shorten the processing run time.
- Modify the expensive part of the system.
Preventive Maintenance:
- It is same as perfective maintenance but the only difference is that it is used to prevent system from failure.
- Preventive maintenance results when programmer or analyzer finds an actual fault that has not yet become a failure and takes action to correct the fault before damage occurs.
- Example : enhancement in fault handling