IRS Logo

2.5.4  Document Standards  (04-01-2005)
Introduction to System Documentation

  1. The introduction provides the purpose, scope, background, and responsibilities of system documentation.  (06-01-2002)
System Documentation — Purpose

  1. The purpose of this manual is to provide standards and guidelines on the preparation of deliverables that constitute documents.

  2. The SDLC requires the completion of mandatory documentation for each phase and stage of software project development.  (06-01-2002)
System Documentation — Scope

  1. The standards and guidelines detailed in this manual apply to all software development projects within the IRS.  (06-01-2002)
System Documentation — Background

  1. The software development process results in a significant amount of documentation. In developing a system, each piece of documentation is an essential building block upon which the next phase is created. Upon completion of a project, certain deliverables, such as module specifications, schematic diagrams, and Computer Operations Handbooks, are kept as formal documentation.

  2. The ADP standards are intended to promote consistency among system documentation.  (06-01-2002)
System Documentation — Responsibilities

  1. Applications Development personnel must adhere to the standards as outlined in this guideline.

  2. If compliance to the established standards for system documentation is impossible: because of system specific characteristics, imposition of unreasonable costs, or for other valid reasons is considered not to be in the best interest of the Service, then an application for a Standards Waiver must be submitted to the National Office Software Quality Group.  (06-01-2002)
General Preparation Standards

  1. These general preparation standards provide for the various components of the system documentation.  (06-01-2002)

  1. Assign a System-ID to each system. In the cases where the structured methodology is used, computer specialists determine the scope of a system by the context diagram in the system’s Functional Specification Package (FSP).

  2. The System-ID must appear in the page header, and serves to link the individual development documents.  (06-01-2002)
Standard Page Information

  1. Every page of applications documentation within an organization/project must contain standard header data. The following type of information will be included on each page for identification purposes:

    • System name

    • System-ID

    • Project number (optional)

    • Related Analysis Specification Document number, e.g., FSP number, when available

    • Responsible organization. Region, Service Center, Division; branch/section; person’s name (optional)

    • Operational date

    • Revision date

    • Transmittal number

    • Run/file/record reference number

  2. For Schematic Diagrams, this information will appear in the title block of Form M–4327 or comparable form.  (06-01-2002)
Page Size

  1. Page size considerations must lead to neat packaging of the document without sacrificing legibility. Reduce oversize pages to 81/2" by 11" for final publication.  (06-01-2002)
Page Numbering

  1. Each page will be assigned Arabic numerals sequentially to the end of the document. When adding new pages between those already issued, a decimal system will be used (e.g., to insert a page between 7 and 8, assign it page number 7.1).

  2. If electronic media is used, or a specific type of documentation could be more advantageously numbered, choose the best method of numbering and insertion specific to the system.  (06-01-2002)
Naming Conventions

  1. The names of programs, modules, files, groups (including records), and items, must be in accordance Data Naming Standards.

  2. All identifiers (names and numbers) must be consistent throughout the different types of documentation (Record Layouts, Computer Operations Handbooks, Run Descriptions, etc.).  (06-01-2002)
General Rule

  1. Avoid redundancy in all applications documents.  (06-01-2002)
Original Run Packaging Considerations

  1. Documentation for periodic or optional runs is included with all other materials developed under the scope of a given FSP or requirements analysis document.

  2. Schematics for a system must indicate where and when an optional run is executed.

  3. Optional runs need not have an entirely separate set of documentation.

  4. Avoid duplication of record layouts, specifications, etc.  (06-01-2002)
Preparation For Publication

  1. If required according to site/system procedures, the following procedures must be followed when preparing the Public Service Requisition (Form 1767):

    1. Item 22. Is security handling required? Check "YES" box.

    2. Item 22a. Available to the public under FOl Act? Check "NO" box. The person signing under Item 23 should also initial this item.

    3. Section B. Additional Instructions—As a further explanation of Item 22, insert the words "Security Level 3" . This will indicate that the lowest level of security will be in effect during the publishing process.

  2. Further procedures for the publication of transmittal documentation may be established by individual organizations, e.g., through CyberDOCS. Refer to system and organization specific instructions for this information.  (06-01-2002)
Transmittal Number and Transmittal Dates

  1. The transmittal numbers and dates entered on the documentation pages must be the same transmittal number and date used to transmit to production the corresponding program, control language or operating procedures described on that page of the documentation.

  2. If a change is issued affecting the procedures described, or information on a particular page, the change page is issued with the new transmittal number and date.  (06-01-2002)
Data Dictionary — Purpose

  1. The Data Dictionary (DD) is a central repository of information about the organization's data, used to maintain control over the definition and use of the data resources. In the Design stage, it is used to:

    1. Determine which, if any, data elements are already used by other systems and/or databases;

    2. Document all elements for a given system; and

    3. Inventory all elements used by a system.

  2. Data entered in the system glossary during the Analysis stage must be updated in subsequent stages such as when the physical attributes are determined or the file design is formulated. Design documentation is updated in more detail in the Data Dictionary to reflect these additions/changes.  (06-01-2002)
Project Library — Purpose

  1. The Project Library is created and maintained for audit, development and maintenance purposes through out all phases of software generation. Its contents are not restricted to Development phase documentation. Documentation is added to the library as it is generated at various points in the Software Development Life Cycle. It consists of specific Initiation, Development, and Operation phase deliverables.

  2. Material produced during the Development phase should be retained as part of the project documentation in the Project Library. Notes, memos, changes or quality review reports, along with any updates, should be filed in the Project Library. This will ensure that Analysis, Design, and Programming documentation created during the Development phase will interface with the documentation created during the subsequent Initiation and Implementation phases. See Exhibit 2.5.4–1 for a display of what materials go into the Project Library during the Development phase. The project/team leader or other appropriate individual can retain a physical copy of the project library, store it on DOCS Open or maintain it in some other repository, electronic or otherwise.  (06-01-2002)
System Description Documentation

  1. This documentation addresses the various components of a system description.  (06-01-2002)
System Description — Standard

  1. A System Description is required for each Automated Data Processing (ADP) system.  (06-01-2002)
System Description — Purpose

  1. The System Description serves as an introduction to the system, and provides any system-specific information which may be important for the reader to know. It is created in the Design stage of software development, when the physical design is fixed; and is updated as necessary.  (06-01-2002)
Contents and Organization

  1. The System Description will contain a general description that defines the scope of the system, identifies external interlaces, and provides the reader with any background information relevant to the system as a whole. The general description will always be the first item addressed.

  2. The System Description may also include, but is not limited to, the following topics:

    • General operating environment considerations such as equipment, system/subsystem controls, differences based on site, etc.;

    • Security/Privacy requirements;

    • Failure contingencies such as back-up or fall-back capabilities;

    • Brief descriptions of optional run streams;

    • Number and type of runs/programs;

    • Data base characteristics such as storage allocation, device types, logical data relationships, access methods, etc., and

    • On-line transaction processing capabilities and requirements.  (06-01-2002)
Preparing a System Description

  1. The size of the description and the amount of detail are dependent upon the size and complexity of the system being described.

  2. A Sample System Description Outline is presented in Exhibit 2.5.4–2.  (06-01-2002)
System Schematic Diagram Documentation

  1. This documentation provides the generic information, contents, and organization for the system schematic.  (06-01-2002)
System Schematic — Standard

  1. A System Schematic Diagram is required for each ADP system. It is created during the Design stage of software development and must be developed in accordance with the standards outlined in this chapter.  (06-01-2002)
System Schematic — Purpose

  1. Schematic Diagrams give a general overview of the work flow in a computer system and visually illustrate the relationships between the numerous computer runs in a system, as well as their input and output files.

  2. Schematic Diagrams provide:

    • Management and testing personnel with the general overview of the computer runs involved in a system;

    • Project and programming supervisors with a tool for establishing workload requirements;

    • A reference for the control and disposition of all established input and output files; and

    • The operations scheduler with a graphic representation for job set-up and operational procedures.  (06-01-2002)
System Schematic — Background

  1. Analyze all requirements analysis material, that is, the Programming Requirements Package (PRP), Functional Specification Package (FSP), or comparable system/site specific documents. (Analysis must take place prior to the development of schematics.) These are deliverables of the Analysis stage, the first stage of the development phase. These documents are passed on to the system designers and communicate to them the functional requirements of the system under development.

  2. The affected development areas must work together when involved in related projects to prepare Schematic Diagrams in accordance with the procedures and standards prescribed in this guideline.

  3. Ensure that approved amendments are incorporated as the development effort progresses in this and subsequent phases.

  4. Review the System Schematic Diagrams periodically to ensure that they conform to the objectives and requirements expressed in the requirements analysis material.  (06-01-2002)
Contents and Organization

  1. Identify on each Schematic Diagram:

    • Computer runs/processes;

    • Terminal and intermediate files; and

    • Off-line machine operations related to the computer runs.

  2. Organize the system into logically related groups of processes (runs and off-line operations) such as daily processing, weekend processing, etc. Each of these groups will become a separate diagram subset.

  3. To the extent possible, depict the runs and operations within each diagram in a sequence that will reflect the actual order of processing.

  4. The final schematics covering the entire system will usually consist of several diagrams (or "sheets" ), each containing a logical group of runs and operations. Use the appropriate connector symbols to provide a link between these diagrams.

  5. Organize the Schematic Diagrams in ascending order of runs based on sequential interdependence.  (06-01-2002)
Preparing a Schematic Diagram

  1. This documentation provides instructions for preparing a schematic diagram.  (06-01-2002)
Run Numbers

  1. Once a software developer requests a run number, the Software Quality Group (SQG) analyst should have the software developer complete the Run Number Registration Form, Form 11363. The SQG analyst should request a description of the computer run. This information should include the name of the system, project, and if the requested computer run is related to any other run number previously issued, etc. This information will assist in issuing the run number.

  2. A run number must be developed from the System-ID. For example, given a three character System-ID, the format " SSS-RR(R)" , must be used. SSS = System-ID and RR(R) = run or operation number. Allocate the "RR(R)" numbers to provide for subsequent insertion of other runs when necessary (e.g., 01, 03, 05). Good judgment may dictate the need for more or less spacing between numbers. However, the computer system, tier, or platform may indicate alternative run number sequences in a format different from the guidelines stated in this paragraph.

  3. If the run request is related to a run number previously issued, the SQG analyst should review the information received as well as the SQG run number data base to determine the new run number.

  4. If the run request is not related to a previous run issued, the SQG analyst should review the information received as well as other pertinent information regarding the run request system or project. The SQG analyst should issue the run number associated to the appropriate system or project. For example, if the project is IRP, the SQG analyst should review the run number data base and issue the new run number with the next available number (e.g., IRP02).

  5. The SQG analyst should record the new run number on the Run Number Registration Form.

  6. The SQG analyst should provide the software developer the assigned run number via an electronic message.

  7. The SQG analyst should enter the information from the completed Run Number Registration Form onto the SQG run number data base. The SQG analyst should place the completed form into the appropriate run number binder, and submit a copy of the new run number form to the PCDOCS administrators. This information may be submitted as often as necessary.  (06-01-2002)
File Numbers

  1. Assign a number to each file which appears on the Schematic Diagram. This number must be developed from the number of the run or operation which creates the file. For example, in a system where the System-ID is composed of three characters, the format "SSSRR(R)FF " shown below can be used. (For additional clarity, hyphens may be used to separate this number—"SSS-RR(R)-FF" , but this an optional feature.) Data set names are allowable if they provide more descriptive information.

    • SSS = System-ID

    • RR(R) = run number

    • FF = a two-digit number (00–99) identifying the file.
      When feasible, the following numbers will be used for FF:
      01–19 Tape Files
      20–29 Disk Files
      40–49 Print Files

  2. An optional "VVV" can be added to the file number (SSSRR(R)FFVVV or SSS-RR(R)-FF-VVV) to indicate variable information such as segment number, region number, service center code, etc. There are several instances when the addition of this variable serves a very useful purpose:

    • To determine the point of origin when the same logical file is sent to several places;

    • To differentiate when a process is run at various sites; or

    • To distinguish when files are sent from multiple sites to one location for consolidation and processing (e.g., District Office files merged at the Regional Office or Service Center files with MCC).  (06-01-2002)
Charting Rules

  1. Schematic diagrams must be prepared on Form M–4327 or a comparable form. A sample Form M–4327 with symbols and instructions is provided in Exhibit 2.5.4–3. The information contained in the ‘Title Block’ of this exhibit must be carried on any comparable form or automated form chosen for this purpose.

  2. Depict as clearly as possible the flow of data through the computer runs and related off-line operations in an efficient sequence.

  3. Identify every input and output file (intermediate and terminal) for each run with an appropriate media symbol (see Exhibit 2.5.4–4).

  4. Maintain consistency in the size and symbols used. The relative size of a media symbol does not alter its significance. Thus, a larger symbol may be used to accommodate a longer title.

  5. Label each input and output file symbol. For example, "INDIVIDUAL-MASTER-FILE" or abbreviated— "IMF" . The symbol represents the file medium. Therefore, do not express the medium (e.g., tape) in the title, unless the general I/O symbol is used.

  6. Place the appropriate file number adjacent to each input and output symbol shown on the Schematic Diagram.

  7. A sample Schematic Diagram is shown in Exhibit 2.5.4–6.  (06-01-2002)
Terminal and Connector

  1. When an output file serves as input to two or more runs, identify that file with only one file number. Connect the output symbol to multiple runs with the appropriate terminal or connector symbols (see Exhibit 2.5.4–5).

  2. Use the terminal symbol to identify the source of an input file or the destination of an output file outside the system. This external source may be another run, functional unit, etc. A sample label for this symbol would be—Posting Transaction: 450–45, where ‘450’ is the SYS-ID and ‘45’ is the Run number. Do not use the words "to" and "from" within this symbol.

  3. Use the connector symbol as needed to continue logical flow between functional units within the system. Number this connector in the form ‘S.N.’ where ‘S’ = sheet number and ‘N’ = connector number. Begin a new sequence of connector numbers on each additional sheet.  (06-01-2002)
Run/Operation Box

  1. Identify the run number. A format is shown in Exhibit 2.5.4–6. The run number is shown in the top space of the Run/Operation Box.

  2. Identify the equipment used in this run. This includes both off-line and online computers, or printers used in this operation. It is identified in the left center portion of the Run/Operation Box (see Exhibits 2.5.4–5 and 2.5.4–6).

  3. Identify the processing frequency of the run or operation. The frequency is shown in the right center position of the Run/Operation Box (see Exhibits 2.5.4–5 and 2.5.4–6).

    1. Express frequency as follows:

      D = daily Q = quarterly O = one time only
      W = weekly S/A = semi-annually P = periodic
      M = monthly A = annually V = variable

    2. Periodic (P) processing applies to those runs which have a specific run interval not represented by D, W, M, Q, S/A, A or O (e.g., bi-monthly).

    3. Variable (V) processing is used when no frequency is specified (e.g., upon demand).

  4. List the run name in the lower portion of the Run/Operation Box. The name should relate to what the run accomplishes (e.g., Sort by Account Number, Sort and Edit, Translate, Merge, Convert PC to MT, Validate, Update).  (06-01-2002)
Multiple Processes on Schematic Diagrams

  1. In some cases, it will be necessary to show multiple copies of the same run being executed at the same time on Schematic Diagrams. See Figure 2.5.4–1 for one way to show multiple processes.

  2. If the number of runs is so large that this method (Figure 2.5.4–1) clutters the page or is unworkable, an alternate method would be to use a footnote to explain that multiple copies of the run are to be executed. Regardless of the method used, this should be documented in the Run Descriptions, Schematic Diagrams and Computer Operations Handbooks.

    Figure 2.5.4-1

    This image is too large to be displayed in the current screen. Please click the link to view the image.

    Multiple Processes on Schematic Diagrams  (06-01-2002)
Run Description Documentation

  1. This documentation provides the generic information, contents, and organization for the run description.  (06-01-2002)
Run Description — Standard

  1. A Run Description is required for each individual computer run in a system.  (06-01-2002)
Run Description — Purpose

  1. Each run is described so that it can be understood with only a general background in computer technology.  (06-01-2002)
Run Description — Contents and Organization

  1. Each Run Description will contain the:

    • Run name;

    • Run synopsis;

    • List of files accessed; and

    • Internal and external controls.

  2. The Run Descriptions will be organized in run number sequence.  (06-01-2002)
Preparing Run Descriptions

  1. This documentation provides instructions for preparing the run description.  (06-01-2002)
Run Synopsis

  1. Prepare a brief, accurate, clear narrative describing the function of each computer run program.

  2. Identify the purpose of the run; that is, what it is intended to accomplish. List any pertinent facts about the run, such as externally called programs. If one run is used for daily, weekly, and yearly processing, etc., and different actions occur during each iteration, spell out the different actions. Do not include statements as to " how" the routines in the program process the data.

  3. Provide a cross-reference list between individual runs and the corresponding processes (e.g., bubbles on the DFDs). When many levels of decomposition are encompassed by one run, only the highest level process which is uniquely identified needs to be referenced.

More Internal Revenue Manual