System documentation represents a collection of documents that illustrates the system and its components. It can include requirements documents, design decisions, architecture descriptions, operation, program source code, and maintenance of a system.

Applying standards for system documentation shall ensure correct: creation, formatting, revising and distributing IT system development information and communication on behalf of the IRS.

Establishing Information Technology document standards promotes consistency pertaining to all technical material, regardless of content, and is a critical operating strategy.

IRM 2.5.1 System Development is the overarching IRM for the System Development program within the IRS

The Clinger-Cohen Act of 1996

Federal Information Security Modernization Act of 2014, FISMA 2014

Government Performance Results Act (GPRA)

Administrator of the Government Service Administration (GSA)

Presidential American Technology Council, 2017

Treasury Inspector General Tax Administration (TIGTA)

All IT organizations responsible for system documentation must adhere to the standards as outlined in this guideline to ensure all activities are accomplished.

If compliance to the established standards for system documentation is impossible, because of system specific characteristics, imposition of unreasonable costs, or other valid reasons that are not in the best interest of the IRS, then the scenario must be reported first to AD senior leadership and submitted to the National Software Quality Group.

Application Development’s (AD) chain of command and responsibilities are:

OneSDLC is a new flexible delivery model created by and for the IRS that provides guardrails for quality, compliance, and executive oversight, while guiding teams from funding to delivery value as quickly as possible without impacting quality. The IRS will be transitioning all current ELC delivery paths from waterfall to a singular, consistent Agile approach. Documentation will be digital and contained within Engineering Workflow Management (EWM) User Stories and possibly other places like DocIT.

Program Effectiveness: The Enterprise Architecture (EA) office organizes quality reviews for all technical projects ensuring system documents are fully aligned with EA principles.

NIST Special Publication 800-53 Rev. 4., Security Controls (SA-5) for "Federal Information Systems and Organizations" establishes the controls for Information System documentation, see https://nvd.nist.gov/800-53/Rev4/control/SA-5

For additional SA-5 controls applicable to the IRS see, IRM 10.8.1.

For Acronyms and Terms, see Exhibit 2.5.4-12

For Terms and Definitions, see Exhibit 2.5.4-13

The resources below provide information for system development documentation standards from NIST, IRS IRMs, and the IRS organizations’ SharePoint repository sites:

Ensure there is a common understanding among Development Team members and stakeholders for all SDLC phases.

Facilitate meetings to serve as a reminder of the specified plans for complex projects, and implement routine deliverable reviews to correct inaccuracies and clarity.

Provide IRS senior management and other stakeholders an insight into the project risks and continuing performance supporting Risk Management initiatives.

Encourage the use of repeatable and consistent processes.

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡

For more information on ELC Coaching, see IRM 2.16.1.13.1 Consult with an ELC Coach for recommended technical approaches for one of the following ELC paths pertaining to new development projects:

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡

Maintain comprehensive records of project performances that could be useful for other project initiatives, e.g. staff knowledge transfer, budgetary activities, and lessons learned.

Depending on the methodology used (agile vs. waterfall) during system development process under Enterprise Life Cycle (ELC) phase, the amount of project documentation produced will vary, and each piece of documentation is an essential building block for the next phase created. After completion of an IRS project some deliverables (artifacts) are expected as seen below:

For more information on common software development artifacts , see Exhibit 2.5.4-20 for "IRS Best Practices Implementing System Development Documentation" , this table is a depiction of the goals and recommended deliverable outcomes.

≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

For more information on PCLIA, see IRM 10.5.2.2.5.1 Survey PCLIA

As prescribed by the Project Management Book Of Knowledge (PMBOK) guide, a project charter is a document that is the first step for implementing a project, it summarizes the key elements and is referenced throughout the project life cycle. Additionally, the charter appoints a project manager with written authority to begin working the project.

See Exhibit 2.5.4-14 for the common sections in an IRS EA ELC project charter.

The Business System Report (BSR) is one document that replaced three retired Data Item Descriptions (DIDs): Business System Concept Report (BSCR), Business System Architecture Report (BSAR), and Business System Requirements Report (BSRR). The BSR documents the vision or concept, architecture and requirements analysis that form the basis for business solution design, development, integration, and testing The BSR consist of three sections:

All sections in the BSR combined form the foundation for the: business solution design, development, integration, testing, and deployment.

The BSR is prepared during the ELC Domain Architecture phase, prior to Milestone 2, and published in the project life cycle in accordance with the project tailoring plan.

The Iterative Business System Report is designed for projects that follow the ELC Iterative Path, and is published at Milestone (MS)1/2. However, this BSR does not further decompose and extend into MS 3/4a/4b phase. The focus is the following:

The Vision Scope and Architecture document defines the vision, sets the scope, architecture boundaries and constraints for iterations or sprints. The VSA is a ELC project level artifact for system development, and is applicable to all Agile projects. Decomposition and refinement within those bounds from sprint to sprint is expected; however, any changes to the scope and architecture already established in the VSA shall require a Change Request (CR) through the formal change control process.

The purpose of the VSA is to provide confirmed evidence that the project’s scope and architecture definition was completed. Alternatives may be proposed by project teams and approved by EA/REPO as part of a proposed ELC tailoring plan. The following is standard format guidance for creating components of the VSA:

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡

Formal document that details all features and specifications of a certain system product. during the Requirements phase of the software development process. The objective of creating a Functional Specification Report (FSP) is to provide all technical information about your collections of system components that interface with other independent systems built to exchange data from the origination point, across the boundary point then deliver the information to its destination.

The interface may include multiple interactions between the systems, e.g.( system A sends a message to system B, and system B replies with a confirmation or response to system A)

FSP/SDSR establishes an agreement on the conditions and responsibilities at the boundary point of independent systems and provide a unifying, end-to-end view of the interface process.

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

An Analysis of Alternatives (AoA) is an analytical evaluation of the different choices for a project’s operational effectiveness, cost, gaps, shortfalls and risks of a proposed objective, and must be created using IRS approved software, e.g. Microsoft Word. The AoA must be completed, approved, and signed by EA leadership at the start of the project. An example of the components / topic areas for the AoA report is listed below:

Weighted Scoring Method (WSM) - Weighted scoring prioritization is a framework designed to help you determine how to prioritize features and other initiatives for your project. Initiatives are scored based on a common set of criteria on a cost versus benefit basis, and then ranked by their final scores. WSM is a useful tool for making decisions such as:

The outcome for the most beneficial product reflected in the WSM table viewed above IRM 2.5.4.4.2. is the LG monitor with the score (★38).

Advantages of WSM:

A Proof of Concept is a process of verification if specific ideas or methods are feasible. The Proof of Concept is usually kept incomplete and small for cost and time efficiency goals. PoC normally occurs during Logical Design, Physical Design and new Development phases when the project team need to prove that an idea or multiple ideas will work.

A PoC report documents the findings from the PoC. For software development, PoC is important for the following reasons:

The IT Strategy & Planning, Business Planning and Requirements Management (BPRM) Office is responsible for the oversight of the IRS IT Demand Management program and Unified Work Request. process. The main goal of Demand Management is to register all requirements for IT products and services.

The Unified Work Request (UWR) process: This process uses work requests to represent a contract between IT and IRS Business Operational Divisions (BODs) and Functional Operating Divisions (FODs) also known as the requestor. Requests for IT products and services from IT are collected into a single system using a common set of processes and procedures.

Work Request : A work request is a form of notification to an IT supplier that a requestor organization has a business need for IT products or services. The work request is necessary for documenting all IT work that is not covered by a Service level Agreement, and is submitted using the Work Request Management System (WRMS). A work request is not required if you are requesting funding for contractors from a contract that is owned and managed by the BOD/FOD and IT services are not requested. The work request types are:

Requestor: Creates and submits the work request for the requesting organization. Pre-coordination with impacted organizations and IT suppliers is recommended. The requester is responsible for the following:

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

A good requirements document template must have at minimum a cover page, section headings, essential guidelines for the content in each section, and a brief explanation of the version change management system used to control changes to the document. Additional template information:

Avoid redundancy in all applications documents.

Implement documentation peer reviews to ensure all content has clarity, correctness, and is relevant to the topic.

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

Technical diagrams for a system must indicate where and when an optional application is executed.

Optional applications need not have an entirely separate set of documentation.

Avoid duplication of record layouts, specifications, etc.

If required according to site/system procedures, the following procedures must be followed when preparing the Publishing Services Request (Form 1767):

Further procedures for the publication of transmittal documentation may be established by individual organizations. Refer to system and organization specific instructions for this information.

Form 3210 is a transmittal used to transfer work documents between domains or organizations. For the transmittal process, the originator shall request the recipient provide an acknowledgement of the work documents’ receipt with a date. The recipient is required to send an acknowledgement copy of the transmitting document back to the originator as evidence the work was received. Document transmittals can be destroyed after one year, per Records Control Schedule (RCS) Document 12990.

For more information on Form 3210 Document Transmittal, see IRM 5.19.16.6http://irm.web.irs.gov/Part5/Chapter19/Section16/IRM5.19.16.aspx#5.19.16.6

A System Description is required for each Information System.

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.

The System Description will contain a general description that defines the scope of the system, identifies internal control environment, external interfaces, 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.

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

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

A Sample System Description Outline is presented in Exhibit 2.5.4–2.

Standard system diagrams are required for each Information System. It is created during the Design stage of software development, and must be developed in accordance with the standards outlined in this chapter.

Process Flow diagrams give a general overview of the work flow in a computer system and visually illustrate the relationships between the numerous computer applications in a system, as well as their input and output files.

Technical diagrams provide:

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 technical documentations.) 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.

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

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

Review the technical diagrams periodically to ensure that they conform to the objectives and requirements expressed in the requirements analysis material.

Use an IRS approved software tool, e.g. Unicom System Architect for creating diagrams.

Use consistent design elements: shapes, lines and text when applicable.

Unified Modeling Language (UML) typical diagrams used by IRS developers include:

For additional information on IRS UML modeling requirement see, IRM 2.5.11 System Development, Analysis Techniques and Deliverables.

Identify on each technical diagram:

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

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

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

Organize the technical diagrams in ascending order of applications based on sequential interdependence.

This subsection provides instructions for preparing a technical diagram.

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

If the number of applications 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 application are to be executed. Regardless of the method used, this should be documented in the Application Descriptions, Technical Diagrams documentation and Computer Operations Handbooks.

An application Description (formally "Run" ) is required for each individual computer application in a system.

Each application is described so that it can be understood with only a general background in computer technology.

Each application Description will contain the:

The Application Descriptions will be organized in application number sequence.

This documentation provides instructions for preparing the application description.

Data Specifications are required for each data structure.

Data Specifications are used to illustrate and define the data structures processed by the computer applications in the system.

Data structures are arranged hierarchically as follows:

The Data Specifications document will contain, in this order:

Information Technology Specialist will sequence the file descriptions and record layouts by record reference number in ascending order. File descriptions will appear in this sequence under record reference number SSS/RR(R)/FF/000, where SSS/RR(R)/FF = file number.

Data Specification headers will contain the system name, responsible organization, operational date, revision date and the file or record reference numbers (see Exhibit 2.5.4-7 .)

This documentation provides the instructions for preparing the data specifications.

A Computer Operations Handbook (COH) is required, which contains a complete set of operating instructions for each computer application in the system. Documents must be prepared with standard IRS tools e.g., MS Word and Visio.

COH provides detailed instructions to a computer operator for the proper execution of an application.

The COH is a required deliverable for the Programming stage of development. However, Computer Operator Messages should be considered first in the Design stage of development. Updating of the COH should be throughout the program development life cycle. Among the items described in the operating instructions are set-up instructions, messages between the program and the operator, the input/output devices used and each file’s name and number.

Arrange instructions in System—ID/Application number sequence.

Document the computer operating instructions in accordance with the following standards and the instructions specified in Exhibits 2.5.4–13 through 2.5.4–18.

Operating instructions forms are published as a full page in the Computer Operations Handbook.

Examples of forms, which are to be used in compiling the Computer Operations Handbook, are shown in Exhibits 2.5.4–13, 2.5.4–15 and 2.5.4–17. These examples include the following forms:

Comparable documents which convey similar information may be used if those listed do not satisfy requirements or are unavailable. Refer to the corresponding system-specific manuals for instructions when preparing those forms unique to particular systems. Instructions for completing the listed forms are in Exhibits 2.5.4–14, 2.5.4–16, and 2.5.4–18 at the end of this document.

Include only those forms that are necessary in the Computer Operations Handbook.

Use language that is clear and concise.

Be consistent in the use of abbreviations, formats, names and terminology, both within the Computer Operations Handbook and between the COH and other related documentation.

Avoid excessive abbreviations to insure readability.

Write the instructions to be implemented by the operator in simple imperative sentences.

For additional information on concise and plain writing see, IRS Writing Style guide

COH title page must consist of the information below:

For more information see table below:

Every physical page (standard 8.5″ by 11″ inch sheet of paper) or its electronic equivalent must contain the standard header and footer information.

After the Title Page, the standard header must consist of the information below:

The standard footer section of each COH page must consist of the information below:

Assign page numbers in unbroken sequence from 1 through "n" for each application, regardless of the number of application options involved.

Enter the page number on each page.

Include the COH Title information at the top of each page.

When application options are not involved, place the required pages in the following sequence:

When options are involved, document each option on separate pages. Place all the pages for each option together and place one option behind the other.

When inserting a new page between existing pages, use a decimal page number, e.g., 5.1.

See Exhibit 2.5.4-16 for an example of a COH with a high-level overview of all outline sections.

≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

Keep operator queries or messages to a minimum.

Console messages should require operator intervention or affect the continued operation of the application stream.

Information messages should appear on the printed listing only.

Console messages should have clear, concise explanations that the operator can follow easily.

If a computer application does not go to EOJ, include a console message to the operator that the contact point designated by the "User-Service Agreement" should be notified.

An IBM Computer Operations Handbook (COH) Guide shall conform to the format depicted in Exhibit 2.5.4-20 . This guide is applicable to the IBM Tier 1 mainframe (except for the Automated Collection System), and applies to all computer specialists developing IBM or IBM-compatible programs.

The IBM COH Guide consolidates the COH, application descriptions, and file specifications into one unified and standard document. Instructions for completing the IBM COH Guide are found in Exhibit 2.5.4-19 .