Topic 4 – Documentation, Evaluation and

Maintenance

Unit 2 – Database Implementation and Testing

Advanced Higher Information SystemsSt Kentigern’s Academy

What I need to know

Description and exemplification of documentation: User Guide, system design documentation (including models and

design of system).

Description of contents and purpose of evaluation: comparison to specification, ease of use, maintainability.

Description of types of maintenance: corrective, adaptive, perfective.

Documentation

Good documentation should be: Clear: it must be easily understood by whoever it was created

for. The language used must be appropriate to the audience - not too complicated for end users and avoiding technical jargon. Terms that may not be understood by everyone need to be explained either the first time they are used or in a glossary. Really detailed technical information could confuse end users of the system. Similarly, technicians don't want instructions such as "click the forward arrow to navigate to the next record" getting in their way when they are trying to troubleshoot problems.

Concise: it should be as possible while still being comprehensive. Using pictures and screenshots can replace hundreds of words and be much clearer. Consider how would you describe the following button to a reader if you had to use words:

Comprehensive: it must not omit important instructions - especially key steps that need to be completed, such as printing, and warnings about what not to do.

Documentation

Up-to-date: if details are out of date, the documentation will be of no value. Printed material is harder to keep current than electronic versions.

Easy to access: it must be available where and when it is needed. This can be a problem with printed material, especially if it is expensive and many copies are required.

Easy to search: users must be able to quickly find the required information. Indexes or tables of contents are required, along with clear headings. Large documents may well need to be divided into sections. For example, there could be a small "Getting Started" brochure with a separate users' manual and technical reference. The idea is that different users need different sorts of information at different times and they don't want a massive single book to plough through to find it.

Documentation – User Guide A User guide is a document that is intended to give assistance to people

working with a particular system. It is can online or a printed book that describes how to use a software application and provides instructions to help users of the database system.

The user guide for a database system should explain how to use the system to produce useful output, not how the system was created. Trying to explain how the system was created will waste time and be irrelevant.

Many user guides incorporate online tutorials and online help facilities.

A tutorial is a series of lessons that guide the users through the basic features of the system. The tutorials should resemble the actual package - the success of the tutorials will depend on the amount of realism built into each lesson. Good tutorials will provide the user with as much access to the program's features as possible. Well designed tutorials allow users to make mistakes, see the results of the mistakes and correct the mistakes with the aid of messages and prompts from the system.

Online help facilities range from a simple command summary screen, which describes all commands simultaneously, to context-sensitive and diagnostic help which depends on where users are in the system and what they are trying to do at the time when help is requested.

Documentation – System The documentation developed at each stage of a system's development

forms the system design documentation.

This documentation is used as a means of communication between every participant involved in the development of the system. If the system project was interrupted for some reason along the way, or if key personnel were replaced, systems design documentation makes it possible for the work to continue.

Later, once the system has been implemented, the systems design documentation acts as a source of information for the Post Implementation Review. The systems design documentation provides management with an accurate gauge to review and evaluate the new system.

The systems design documentation is also needed if changes to the system are necessary at a later stage. In other words, the systems design documentation is needed to carry out maintenance and enhancement of the system. Because maintenance is usually carried out by personnel who were not involved in the original development of the program, members of the maintenance team must have a full understanding of all the functions and logic of the system. If the systems design documentation is unavailable, the work of the maintenance team assigned to make the necessary changes to the system becomes far more difficult.

Post Implementation Review

The Post Implementation Review is a formal evaluation of a new system or project. The PIR is undertaken when there has been time to demonstrate the benefits of the new system. It checks whether benefits have been achieved and identifies opportunities for further improvement.

Without a PIR, you cannot demonstrate that the client's investment in the project was worthwhile.

The purpose of the Post Implementation Review is to: determine the extent to which the project met its objectives,

planned benefits and addressed requirements as originally defined;

examine all aspects of the system to see if further improvements can be made to optimise the benefits delivered. These would be carried out during future maintenance of the system;

find out users' perspective of the system - do they like it, is it easy to use, what difficulties have they come across?

Comparison to Spec

The Post Implementation Review assesses the overall quality of the information system. It checks whether or not the new system meets specified requirements and achieves the anticipated benefits. The requirements and expected benefits should have been defined in the System Specification.

In order to determine the degree to which the operational system matches the system specification, each requirement listed should be considered individually by the evaluation team. The Post Implementation Review must: cover all requirements listed in the system specification; describe the extend to which those requirements have been

achieved; make recommendations in any case where a requirement

has not fully been met or a problem has been identified.

Ease of Use

The Post Implementation Review must take account of the views and opinions of end users of the operational system.

Feedback from users is useful in determining how well the system meets its requirements and identifying possible improvements to the system. User feedback is essential, however, when measuring the user friendliness of the system and determining its ease of use.

Users of the system should be asked to evaluate: the overall performance of the system, user-friendliness of the system, completeness and quality of documentation, quality and effectiveness of training.

Maintainability

During the Post Implementation Review, all aspects of the system are examined to see if further improvements can be made to maximise the benefits delivered. Any such improvements would be carried out during future maintenance of the system.

The Post Implementation Review should also contain recommended actions in any situation where a requirement has not fully been met or a problem has been identified. These actions would be carried out during future maintenance of the system.

Maintainability refers to the ease with which a system can be understood, corrected, adapted or enhanced. Maintainability can be enhanced by: good initial design; comprehensive and accurate system design documentation; use of standards (design, language, coding, etc.) throughout the

development; availability of extensive test cases.

Maintenance

Maintenance refers to any changes that need to be made to a product after it has been handed over to the client. The maintenance of existing software can account for over 60% of all development effort. In this topic we will consider different types of maintenance that can be carried out on an existing database system.

Maintenance is not just about "fixing mistakes" but also includes any post-delivery modification to an existing system. Because a database system consists of more than just database structures and scripts, any changes to documentation, manuals, or any other component of the product are also examples of maintenance.

Maintenance can be categorised into the following four types: Corrective maintenance; Adaptive maintenance; Perfective maintenance; Preventive maintenance

Corrective Maintenance

Corrective maintenance is the most burdensome part of systems maintenance, because it corrects design, coding and implementation errors that should never have occurred.

Since testing of the system should have been systematic and thorough, errors that are discovered after a system is fully operational tend to be very obscure. The need for corrective maintenance can often be traced to poor design during the Systems Analysis and Design Life Cycle. Corrective maintenance may be needed to correct residual faults in specification, design, coding and documentation.

Adaptive Maintenance

Adaptive maintenance is performed to satisfy changes in the processing or data environment and meet new user requirements.

The environment in which the system operates is dynamic therefore the system must continue to respond to changing user requirements.

Preventative Maintenance

Preventive maintenance consists of periodic inspection and review of the system to uncover and anticipate problems.

As members of the maintenance team with a system, they often find defects that signal potential errors. While not requiring immediate attention, these defects, if not corrected in their minor stages, could significantly affect either the functioning of the system or the ability to maintain the system in the future.

Preventative maintenance refers to changes to the system which seek to avoid problems associated with some future crises. The identification and removal of the Y2K bug is an example of preventive maintenance