Table of Contents | Appendix C-20 | Appendix C-22

APPENDIX C-21

MAINTENANCE MANUAL

The Maintenance Manual provides maintenance personnel with the information necessary to maintain the system effectively. The manual provides the definition of the software support environment, the roles and responsibilities of maintenance personnel, and the regular activities essential to the support and maintenance of program modules, job streams, and database structures.

In addition to the items identified for inclusion in the Maintenance Manual, additional information may be provided to facilitate the maintenance and modification of the system. Appendices to document various maintenance procedures, standards, or other essential information may be added to this document as needed.

1.0      INTRODUCTION

This section provides general reference information regarding the Maintenance Manual. Whenever appropriate, additional information may be added to this section.

1.1      Purpose

In this section, describe the purpose of the manual and reference the system name and identifying information about the system and its programs.

1.2      Points of Contact

This section identifies the organization(s) responsible for system development, maintenance, and use. This section also identifies points of contact (and alternate if appropriate) for the system within each organization.

1.3      Project Reference

This section provides a bibliography of key project references and deliverables produced during the information system development life cycle. If appropriate, reference the FRD, Systems Design Document, Test Plan, Test Analysis Report(s), Operations Manual, User Manual, load module description, source code description, and job control language (JCL) description.

1.4      Glossary

Provide a glossary with definitions of all terms, abbreviations, and acronyms used in the manual. If the glossary is several pages in length, place it as an appendix.

2.0      SYSTEM DESCRIPTION

The subsequent sections provide an overview of the system to be maintained.

2.1      System Application

This section provides a brief description of the purpose of the system, the functions it performs, and the business processes that the system is intended to support. If the system is a database or an information system, include a general description of the type of data maintained, and the operational sources and uses of those data.

2.2      System Organization

In this section, provide a brief description of the system structure, major system components, and the functions of each major system component. Include charts, diagrams, and graphics as necessary.

2.3      Security and the Privacy Act

This section provides an overview of the system's security controls and the need for security and protection of sensitive data. For example, include information regarding procedures to log on/off of the system, provisions for the use of special passwords, access verification, and access statuses as appropriate. If the system handles sensitive or Privacy Act information, include information regarding labeling system outputs as sensitive, or Privacy Act-related. In addition, if the system is covered by the Privacy Act, include a warning of the Privacy Act's civil and criminal penalties concerning the unauthorized use and disclosure of system data.

2.4      System Requirements Cross-Reference

This section contains an exhibit that cross-references the detailed system requirements with the system design document and test plan. This document, also referred to as a traceability matrix in other documents, assists maintenance personnel by tracing how the user requirements developed in the FRD are met in other products of the life cycle. Because this information is provided in the system design document, it may be appropriate to repeat or enhance that information in this section.

3.0      SUPPORT ENVIRONMENT

This section describes the operating and support environment for the system and program(s). Include a discussion of the equipment, support software, database characteristics, and personnel requirements for supporting maintenance of the system and its programs.

3.1      Equipment Environment

This section describes the equipment support environment, including the development, maintenance, and target host computer environments. Describe telecommunications and facility requirements, if any.

3.1.1 Computer Hardware

This section discusses the computer configuration on which the software is hosted and its general characteristics. The section should also identify the specific computer equipment required to support software maintenance if that equipment differs from the host computer. For example, if software development and maintenance are performed on a platform that differs from the target host environment, describe both environments. Describe any miscellaneous computer equipment required in this section, such as hardware probe boards that perform hardware-based monitoring and debugging of software. Include any telecommunications equipment.

3.1.2 Facilities

This section describes the special facility requirements, if any, for system and program maintenance and includes any telecommunications facilities required to test the software.

3.2      Support Software

This section lists all support software--such as operating systems, transaction processing systems, and database management systems (DBMSs)--as well as software used for the maintenance and testing of the system. Include the appropriate version or release numbers, along with their documentation references, with the support software lists.

3.3      Database Characteristics

This section contains an overview of the nature and content of each database used by the system. Reference other documents for a detailed description, including the system design document as appropriate.

3.4      Personnel

This section describes the special skills required for the maintenance personnel. These skills may include knowledge of specific versions of operating systems, transaction processing systems, high-level languages, screen and display generators, DBMSs, testing tools, and computer-aided system engineering tools.

4.0      SYSTEM MAINTENANCE PROCEDURES

This section contains information on the procedures necessary for programmers to maintain the software.

4.1      Conventions

This section describes all rules, schemes, and conventions used within the system. Examples of this type of information include the following:

•      System-wide labeling, tagging, and naming conventions for programs, units, modules,
       procedures, routines, records, files, and data element fields
•      Procedures and standards for charts and listings
•      Standards for including comments in programs to annotate maintenance modifications and
       changes
•      Abbreviations and symbols used in charts, listings, and comments sections of programs

If the conventions follow standard programming practices and a standards document, that document may be referenced, provided that it is available to the maintenance team.

4.2      Verification Procedures

This section includes requirements and procedures necessary to check the performance of the system following modification or maintenance of the system's software components. Address the verification of the system-wide correctness and performance.

Present, in detail, system-wide testing procedures. Reference the original development test plan if the testing replicates development testing. Describe the types and source(s) of test data in detail.

4.3      Error Conditions

This section describes all system-wide error conditions that may be encountered within the system, including an explanation of the source(s) of each error and recommended methods to correct each error.

4.4      Maintenance Software

This section references any special maintenance software and its supporting documentation used to maintain the system.

4.5      Maintenance Procedure

This section describes step-by-step, system-wide maintenance procedures, such as procedures for setting up and sequencing inputs for testing. In addition, present standards for documenting modifications to the system.

5.0      SOFTWARE UNIT MAINTENANCE PROCEDURES

For each software unit within the system, provide the information requested. If the information is identical for each of the software units, it is not necessary to repeat it for each software unit. If the information in any of the areas discussed below is identical to information provided in Section 4, System Maintenance Procedures, for the system maintenance procedures, then reference that area. This section should contain the following:

•      Unit Name And Identification--Provide the name or identification of each software unit
       that is a component of the system. Repeat the following information for each unit name.

•      Description--Provide a brief narrative description of the software unit. Reference other
       sections within the life cycle that contains more detailed descriptive material.

•      Requirements Cross-Reference--Include the detailed user requirements satisfied by this
       particular software unit. It may be a matrix that traces the system requirements from the
       FRD through the system design document and test plan for the specific software units.
       Other life cycle documentation may be referenced as appropriate.

•      Conventions--Describe all rules, schemes, and conventions used within the program. If
       this information is program-specific, provide that information here. If the conventions are
       all system-wide, discuss them Section 4. If the conventions follow standard programming
       practices and a standards document, that document may be referenced here.

•      Verification Procedures--Include the requirements and procedures necessary to check
       the performance of the program following modification or maintenance and addresses the
       verification of program correctness, performance, and detailed testing procedures. If the
       testing replicates development testing, it may be appropriate to reference the original
       development test plan.

•      Error Conditions--Describe all program-specific error conditions that may be
       encountered provide an explanation of the source(s) of each error, and recommend
       methods to correct each error. If these error conditions are the same as the system-wide
       error conditions described in Section 4.3, Error Conditions, that section may be
       referenced here.

Listings--Provide a reference to the location of the program listings.

Maintenance Manual Outline

Cover Page
Table of Contents

1.0       INTRODUCTION
            1.1       Purpose
            1.2       Points of Contact
            1.3       Project References
            1.4       Glossary

2.0       SYSTEM DESCRIPTION
            2.1       System Application
            2.2       System Organization
            2.3       Security and the Privacy Act
            2.4       System Requirements Cross-Reference

3.0       SUPPORT ENVIRONMENT
            3.1       Equipment Environment
            3.2       Support Software
            3.3       Database Characteristics
            3.4       Personnel

4.0       SYSTEM MAINTENANCE PROCEDURES
            4.1       Conventions
            4.2       Verification Procedures
            4.3       Error Conditions
            4.4       Maintenance Software
            4.5       Maintenance Procedures

5.0       SOFTWARE UNIT MAINTENANCE PROCEDURES

Table of Contents | Appendix C-20 | Appendix C-22