2.5.4 Document Standards

Manual Transmittal

July 06, 2020

Purpose

(1) This transmits revised Internal Revenue Manual (IRM) 2.5.4, Information Technology, Systems Development, Document Standards

Material Changes

(1) Changed name and title from Terrance H. Lutes, Chief Information Technology Services to Nancy Sieger, Associate Chief Information Officer (ACIO) Application Development

(2) 2.5.4.1, Added Program Scope and Objectives

(3) 2.5.4.1.1, Added Background

(4) 2.5.4.1.2, Added Authority

(5) 2.5.4.1.3, Added Roles and Responsibility

(6) 2.5.4.1.4, Added Program Management Review

(7) 2.5.4.1.5, Added Program Controls

(8) 2.5.4.1.6, Added Acronyms/Terms

(9) 2.5.4.1.7, Added Terms/Definitions

(10) 2.5.4.1.8, Added Related Resources

(11) 2.5.4.2, Added System Development Documents(SDLC Enterprise Life Cycle Phases

(12) 2.5.4.2.1, Added IRS System Development Documentation Best Practices

(13) 2.5.4.2.1, Added a Table for IRS Best Practices - Implementing System Development Documents

(14) 2.5.4.3, Added Preparation Standards for System Development Documents

(15) 2.5.4.3.1, Added Analysis of Alternatives(AoA) Document Format - Non ELC

(16) 2.5.4.3.1, Added a Table for Example - Weighted Scoring Method (WSM)

(17) 2.5.4.3.2, Added Vision Scope and Architecture (VSA) (Agile)

(18) 2.5.4.3.3, Added Unified Work Request (UWR) - non ELC

(19) 2.5.4.3.4, Added, Business System Report - ELC Document (Waterfall)

(20) 2.5.4.3.4.1, Added Business System Report Benefits

(21) 2.5.4.3.4.2, Added Business System Report (BSR) Standard Format

(22) 2.5.4.3.3, Added Unified Work Request (UWR) - non ELC

(23) 2.5.4.3.4, Added Business System Report - ELC Document (Waterfall)

(24) 2.5.4.3.4.1, Added Business System Report Benefits

(25) 2.5.4.3.5, Added Alterative Business System Report (BSR) - ELC Document (Agile)

(26) 2.5.4.3.6, Added Project Charter Outline - ELC Document

(27) 2.5.4.3.7, Added Functional Specification Report (Also Known as Simplified Design Specification Report (SDSR)

(28) 2.5.4.3.7.1, Added FSP/SDSR Standard Title page Template

(29) 2.5.4.3.7.2, Added FSP/SDSR Standard Document Template

(30) 2.5.4.3.14, Preparing Form 3210, Document Transmittal

(31) 2.5.4.4, Added Preparation Requirements - Non-ELC documentation

(32) 2.5.4.5, Added Document Version Control Standards

(33) 2.5.4.6 (1), Data Dictionary Purpose - Added a paragraph for a description Data Dictionary

(34) 2.5.4.7, Added Primary Project Libraries - IT Process Assets Library (IT PAL) and DocIT

(35) 2.5.4.7.5.2 (2), Subsection removed because it was no longer relevant. Information is on SharePoint site as stated in section 2.5.4.7

(36) 2.5.4.8 (1), System Description Documentation, replaced the word documentation with subsection

(37) 2.5.4.8.4, Included System Technical Diagram Documentation to title Contents and Organization for more clarity

(38) 2.5.4.8.5.1, Removed the word Run in title Run Application Numbers and replaced with Application

(39) 2.5.4.8.5.5, Application/Operation Box, Table added Title and converted Header row to 508 compliance requirement

(40) 2.5.4.11.4.2, Changed incorrect punctuation

(41) 2.5.4.11.4.3 (3),Changed incorrect punctuation

(42) 2.5.4.11.4.4.4, Changed exhibit from 2.5.4-11 to 2.5.4-6

(43) 2.5.4.12.1, Included IRS to the title Standard

(44) 2.5.4.12.4 COH Operating Instructions. Converted Header row to 508 compliance requirement and modified table attributes to include description and table format.

(45) 2.5.4.12.6, Added COH - Title Page Template, Converted Header row to 508 compliance requirement and modified table attributes to include description and table format.

(46) 2.5.4.12.9, Added link for Computer Operation Handbook template

(47) 2.5.4.12.7, Added COH - Standard Header and Footer Information

(48) 2.5.4.12.9, Added COH Standard Outline

(49) Converted all tables to 508 compliant requirement, and included titles throughout this IRM

(50) Entire IRM, redacted all IRS internal links.

(51) Throughout IRM, changed Schematic to Technical Diagram

(52) Throughout IRM, changed PCDOCS to IT PAL

(53) Exhibit 2.5.4-1, Sample System Description Outline, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(54) Exhibit 2.5.4-2, Technical Diagram, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(55) Exhibit 2.5.4-3, Sample Data Specifications, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(56) Exhibit 2.5.4-4, File and Record Index Instructions, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(57) Exhibit 2.5.4-5, Master Record Layout, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(58) Exhibit 2.5.4-6, Instructions for Completing the IBM Core Record Layout, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(59) Exhibit 2.5.4-7, Instructions for Completing Form 3864 I/O Units, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(60) Exhibit 2.5.4-8, Instructions for Completing Form 3864A-Set Up, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(61) Exhibit 2.5.4-9, Instructions for Completing Form 3864D-Message List, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(62) Exhibit 2.5.4-10, Instructions for Completing the IBM COH Guide, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(63) Exhibit 2.5.4-11, IBM COH Guide, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(64) Exhibit 2.5.4-12, Acronyms and Terms

(65) Exhibit 2.5.4-13, Terms and Descriptions

(66) Exhibit 2.5.4-14, Added Project Charter Content, Converted Header Row to 508 compliance requirement and modified table attributes to include description and table format.

(67) Exhibit 2.5.4-15, Added Enterprise Architecture - Interactive ELC Artifact BY Phase Chart.

(68) Exhibit 2.5.4-16, Added Example - Computer Operations Handbook Outline.

(69) Exhibit 2.5.4-17, Added Example - Business System Report Template.

(70) Exhibit 2.5.4-18, Added Vision Scope and Architecture (VSA) Document Components.

(71) Exhibit 2.5.4-19, Added FSP/SDSR Standard Document Components.

Effect on Other Documents

IRM 2.5.4 dated 04-01-2005 is superseded. Additionally, this IRM supplements IRM 2.5.1 Information Technology, System Development and IRM 2.5.3 Information Technology, System Development, Programming and Source CodeStandards

Audience

The provisions in this transmittal apply to personnel responsible for engineering, developing, or maintaining Agency software systems identified in the IRS Enterprise Architecture, and include:

Effective Date

(07-06-2020)


Nancy Sieger
Acting Chief Information Officer

Program Scope and Objectives

  1. Purpose: This manual is to provide standards and guidelines for the preparation of all system development / software development project deliverables that consist of project documents to include Enterprise Life Cycle (ELC) documentation. The System Development Life Cycle (SDLC), and Enterprise Architecture and the Enterprise Life Cycle (ELC) requires the completion of mandatory documentation (artifacts) for new software development following any ELC Path and planned maintenance.

  2. Audience: This guidance applies to all IRS Senior leadership, Information Technology (IT) managers at all levels. Also included are personnel responsible for: engineering, programming, and architecture, or maintaining Agency software systems identified in the IRS Enterprise Architecture including:

    1. All IRS IT business operations and functional units responsible for implementing, verifying and validating software development documentation (artifacts).

    2. External business associates and organizations under contractual arrangements with the IRS; i.e., contractors, vendors, and outsourcing providers.

  3. Policy Owner: The Associate, Chief Information Officer (ACIO), Application Development establishes all Information Technology internal controls for this IRM.

  4. Program Owner: The Application Development (AD) Director, Technical Integration Organization is the program owner.

  5. Primary Stakeholders:

    1. All Application Development Executive Management

    2. All Internal Revenue Service (IRS) IT Managers

    3. IRS Information Technology Managers

    4. AD Developers - government employees and contractual personnel

    5. Engineers

    6. Enterprise Architecture domain

    7. Quality Assurance (QA) managers and QA staff

  6. Program Goals: The objective is to make available the technical know-how for all relevant users of this information. Although computer software documentation details are important, it must be written in a language for easy comprehension, see IRS Writing Style guide. This IRM focuses on Industry standards from: IBM, International Standards Organization (ISO), and International Electrical and Electronics Engineers Standards Association (IEEE). This chapter also covers the document process, and how to implement the inclusion of: content, structure, and formats.

Background

  1. 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.

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

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

Authority

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

  2. The Clinger-Cohen Act of 1996

  3. Federal Information Security Modernization Act of 2014, FISMA 2014

  4. Government Performance Results Act (GPRA)

  5. Government Accountability Office (GAO)

  6. Administrator of the Government Service Administration (GSA)

  7. Presidential American Technology Council, 2017

  8. Treasury Inspector General Tax Administration (TIGTA)

  9. 21st Century Integrated Digital Experience Act (IDEA), December 2018

Roles and Responsibilities

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

  2. If compliance to the established standards for system documentation is not possible because of system specific characteristics, unreasonable costs, or other valid reasons that are not in the best interest of the IRS, then the circumstances must be reported to AD senior leadership and AD executive leadership.

  3. Application Development’s chain of command and responsibilities are the following:

    1. Commissioner: Oversees and provides overall strategic direction for the IRS. The Commissioner’s and Deputy Commissioner’s main focus is for the IRS’s services programs, enforcement, operations support, and organizations. Additionally, the Commissioner’s vision is to enhance services for the nation’s taxpayers, balancing appropriate enforcement of the nation’s tax laws while respecting taxpayers’ rights.

    2. Deputy Commissioner, Operation Support (DCOS): Oversees the operations of Agency-Wide Shared Services: Chief Financial Officer, Human Capital Office, Information Technology, Planning Programming and Audit Oversight and Privacy, and Governmental Liaison and Disclosure.

    3. Chief Information Officer (CIO): The CIO leads Information Technology, and advises the Commissioner on Information Technology matters, manages all IRS IT resources, and is responsible for delivering and maintaining modernized information systems throughout the IRS. Assisting the Chief Technology Office (CTO) is the Deputy Chief Information Officer for Operations.

    4. Application Development (AD) Associate Chief Information Officer (ACIO): The AD ACIO reports directly to the CIO; oversees and ensures the quality of: building, unit testing, delivering and maintaining integrated enterprise-wide applications systems to support modernized and legacy systems in the production environment to achieve the mission of the Service.

    5. Deputy AD Associate CIO (ACIO): The Deputy AD ACIO reports directly to the AD ACIO, and is responsible for:
      • Leading all strategic priorities to enable the AD Vision, IT Technology Roadmap and the IRS future state
      • Executive planning, and management of the development organization which ensures all filing season programs are developed, tested, and delivered on-time and within budget

  4. AD has the following Domains:

    1. Compliance Domain

    2. Corporate Data Domain

    3. Customer Service Domain

    4. Data Delivery Service (DDS) Domain

    5. Delivery Management; Quality Assurance (DMQA) Domain

    6. Identity & Access Management (IAM) Organization Domain

    7. Internal Management Domain

    8. Submission Processing Domain

    9. Technical Integration Organization (TIO) Domain

     

  5. Director, Compliance: Provides executive direction for a wide suite of Compliance domain focused applications and oversee the IT Software Development organization to ensure the quality of production ready applications.

    1. Directs and oversees an unified cross-divisional approach to compliance strategies needing collaboration pertaining for the following:

    • Abusive tax avoidance transactions needing a coordinated response

    • Cross-divisional technical issues

    • Emerging issues

    • Service-wide operational procedures

  6. Director, AD Corporate Data: Directs and oversees the provisioning of authoritative databases, refund identification, notice generation, and reporting.

  7. Director, Customer Service: Directs and oversees Customer Service Support for the IT Enterprise Service Desk ensuring quality customer to employee relationship.

  8. Director, Data Delivery Services: Oversees and ensures the quality of data with repeatable processes in a scalable environment. The Enterprise Data Strategy is to transform DDS into a data centric organization dedicated to deliver Data as a Service (DaaS) through:

    • Innovation - new methods, discoveries

    • Renovation - streamline or automate

    • Motivate - incent and enable individuals

  9. Director, Delivery Management & Quality Assurance (DMQA):

    • Executes the mission of DMQA by ensuring AD has a coordinated, cross-domain, and cross-organizational approach to delivering AD systems and software applications

    • Reports to the AD ACIO, and chairs the AD Risk Review Board.

    • Chairperson, Configuration Control Board, see IRM 2.5.1.2.2.2

    • Government Sponsor, Configuration Control Board, see IRM 2.5.1.2.2.2

  10. Director, Identity & Access Management (IAM) Organization: Provides oversight and direction for continual secure online interaction by verification and establishing an individual's identity before providing access to taxpayer information “identity proofing” while staying compliant within federal security requirements.

  11. Director, Internal Management: Provides oversight for the builds, tests, deliveries, refund identification, notice generation, and reporting.

  12. Director, Submission Processing: Provides oversight to an organization of over 17000 employees, comprised of: a headquarters staff responsible for developing program policies and procedures, five W&I processing centers, and seven commercially operated lockbox banks. Responsible for the processing of more than 202 million individual and business tax returns through both electronic and paper methods.

  13. Director, Technical Integration: Provides strategic technical organization oversight ensuring applicable guidance, collaboration, and consolidation of technical integration issues and quality assurance for the Applications Development portfolio.

Program Management and Review

  1. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

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

Program Controls

  1. 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

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

Acronyms/Terms

  1. For Acronyms and Terms, see Exhibit 2.5.4-12

Terms/Definitions

  1. For Terms and Definitions, see Exhibit 2.5.4-13

Related Resources

  1. The resources below provide information for system development documentation standards from NIST, IRS IRMs, and the IRS organizations’ SharePoint repository sites/Uniform Resource Locators (URLs).

    • ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

    • ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

    • NIST Special Publication (SP) 800-100 Information Security Handbook: A Guide for Managers

    • NIST SP 800-53 (Rev. 4) SA-4 (3) Security and Privacy Controls for Federal Information Systems and Organizations

    • IRM 10.8.1 Information Technology (IT) Security, Policy and Guidance

    • IRM 2.16.1 Enterprise Life Cycle Guidance

    • IBM Computer Operations Handbook

System Development Life Cycle Document (SDLC) Enterprise Life Cycle Phases

  1. The Enterprise Life Cycle (ELC) is a project lifecycle management methodology, and is used to support IRS projects by standardizing the approach for repeatable processes, ensuring consistency and compliance of project management best practices. The IRS ELC office SDLC has seven phases relating to system documents or artifacts:

    1. Project Initiation (Planning): Determining the scope of the problem and related solutions pertaining to: benefits, risks, costs, and time.

    2. Domain Architecture (System Analysis & Requirement): Providing functional analysis for the needs of the end-user and stakeholders to ensure the new system meets every expectation.

    3. Preliminary Design (System Design): Implement the detailed technical specifications, features and operations that will satisfy the users’ and stakeholders’ functional requirements.

    4. Detail Design (System Design): Converts the prototype system design in the Design phase into a working information system that reflects all documented system requirements. At the end of this phase, the working system will enter the Test Phase.

    5. System Development (System Integration and Testing): This phase is defined as coding and software testing in an integrated hardware and software environment to verify the behavior of the complete information system, and evaluate the system compliance with federal and industry standards. As an IRS initiative, is implemented with the Delivery Management Quality Assurance (DMQA) domain.

    6. System Deployment (Implementation): All system requirements are completed, and the software program, data and other components are deployed to the production environment.

    7. Operation & Maintenance: Enhancing the system performance, fine tuning system configuration and establishing security controls according to IRS standards.

IRS System Development Documentation Best Practices

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

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

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

  4. Encourage the use of repeatable and consistent processes.

  5. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

  6. 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:

    1. Iterative (Rapid Delivery) - Developing a system by using Agile methodologies e.g., SCRUM: epics, user stories and tasks instead of requirements.

    2. Common Services - Develop a system by using software functions that can be reused in multiple IRS applications.

    3. Commercial-Off-the-Shelf (COTS) - The focus is on commercially provided products for stakeholder required functionality.

    4. Managed Services - Services completed by (third party).

    5. Planned Maintenance - Making changes to a system in a production environment that is scheduled in advance.

    6. Mobile Apps - This is a developed solution that will be an application on either iOS or Android operating system.

    7. SharePoint - Used for projects pertaining to building or maintaining SharePoint sites.

    8. Waterfall - Using well defined requirements that have sequential progression for developing a custom-built solution.

  7. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

  8. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

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

  10. 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:

    1. Project Tailoring Plan (PTP)

    2. Project Management Plan (PMP)

    3. Privacy Package / Privacy and Civil Liberties (PCLIA)

    4. Business System Report (BSR)

    5. Configuration Management Plan (CMP)

    6. Computer Operations Handbook (COH)

    7. Module specifications

    8. Schematic diagrams

    9. System Requirements Specification (SRS) also known as a Software Requirement Specification

    10. Interface Control Document (ICD)

    11. 508 Accessibility and Mitigation Packages

    12. System Deployment Plan (SDP)

  11. 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.

  12. ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

  13. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡"≡ ≡ ≡ ≡" ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

  14. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

  15. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

  16. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

  17. For more information on PCLIA, see IRM 10.5.2.2.5.1 Survey PCLIA

Preparation Requirements - ELC Development Documentation

  1. Additional information for all ELC documents listed in table

  2. For information on the ELC Artifacts Phase Chart see, Exhibit 2.5.4-15

Project Charter Outline - ELC Document

  1. 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.

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

Business System Report - ELC Document (Waterfall)

  1. 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:

    1. Business System Concept: A description of the requirements and problems in the current environment, vision of the future state of the business, and provides a conceptual view of the business system solution.

    2. Business System Architecture: Pertains to the business and system architectures of the selected business solution which includes: business processes, business rules, organizations, locations applications, data, technology (infrastructure), and security.

    3. Business System Requirements: This section captures the feasible, quantifiable and verifiable set of requirement statements that define the business system or subsystem(s) being developed or enhanced. This section also includes traceability for all requirement statements beginning with the enterprise business and information system capabilities from the project charter, and elements of the business system architecture.

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

  3. 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.

Business System Report Benefits
  1. Since the BSR is comprised of three documents: BSCR, BSAR, and the BSRR which is used for the Concept, Architecture and Requirements statements the benefits are:

    1. Eliminates overlapping content in multiple locations.

    2. Creates cost reductions and time efficiencies in document production, instead maintaining three documents only one is necessary.

    3. Traceability between business models, system solutions and requirement statements all exist in one entity.

    4. Improves quality and completeness of business system representation.

Business System Report (BSR) Standard Template
  1. The BSR must be created using Microsoft Word with the following content and format:

    Example - BSR Title page

    Example - BSR Title page Template
    Insert Project Name

    Business System Report

    Document ID: <Insert unique reference number>

    Version Number:
    Effective Date: <MM/DD/YYYY>

    Prepared for:
    Internal Revenue Service (IRS)

    Contract Number:

    Task Order Number:

     

     

  2. See Exhibit 2.5.4-17 for the BSR template displaying all recommended sections.

  3. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

Iterative Business System Report (BSR) - ELC Document (Agile)

  1. 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:

    1. The total scope of the system as reflected in the system objectives, the set of system capabilities, high level process/use cases, system boundary and solution concept, and key constraints and assumptions.

    2. The release is roadmapped for the project and release plan for the next release.

Vision Scope and Architecture (VSA) - ELC (Agile)

  1. 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.

  2. 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:

    1. The VSA must be created using Microsoft Word. See Exhibit 2.5.4-18 for VSA template components:

  3. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

Functional Specification Report (Also Known as Simplified Design Specification Report (SDSR))

  1. 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.

  2. 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)

  3. 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.

  4. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

FSP/SDSR Standard Title page Template
  1. The title page identifies the name and unique reference number assigned to the document, contract and task order numbers.

    Example - FSP/SDSR Title page

    Example - FSP/SDSR Title page Template
    Insert Project Name

    Simplified Design Specification Report

    Document ID: <Insert unique reference number>

    Version Number:
    Effective Date: <MM/DD/YYYY>

    Prepared for:
    Internal Revenue Service (IRS)

    Contract Number:

    Task Order Number:

     
FSP/SDSR Standard Components
  1. The FSP/SDSR must be created using Microsoft Word with Enterprise Architecture specific content and format, see Exhibit 2.5.4-19 for example document sections.

  2. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

Preparation Requirements - Non-ELC documentation

  1. Projects cannot be implemented without the proper requirements. Non-ELC requirements documentation describes how each requirement meets the business needs for the project, and is normally the first step before implementing the project. All requirements must be measurable, traceable, consistent, complete, and acceptable within the guidelines of your management and EA leadership.

  2. All requirements documentation must follow the format guidelines within this IRM and any IRS and industry standard references mentioned.

Analysis of Alternatives(AoA) Standard Format - Non-ELC Documentation

  1. 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:

    Example - Analysis of Alternatives Report Template
    TITLE page with IRS Logo  
    SIGNATURE APPROVAL page Author and Management signatures for approval of content.
    DOCUMENT MODIFICATION HISTORY page Create a chart for annotating: Author date and any changes, deletions or modifications
    EXECUTIVE SUMMARY page with following subject areas: Comprehensive statement of the overall proposal with the following subsections:
    * OVERVIEW Summarization of the capabilities required for the proposal
    • Problem Statement Concise summarized description of issues that need to be addressed.
    • Analysis Objective What is the purpose of submitting an AoA?
    • Analysis Approach What tasks are performed for the outcome of the analysis and by whom - (Domain/Organization)?
    * FINDINGS A written summarization of all information found for the solution of the problem
    • RECOMMENDATIONS From the finding provide at least three Course of Actions (COA) / scenarios for the problem
    TABLE OF CONTENTS page  
    1.0 INTRODUCTION  
    1.1 Problem Definition Explain the gap between the existing state and desired state and/or deviation from the standard.
    1.2 Background Historical information of the issues with the current technical situation at hand
    1.3 Objective Write an explanation of the goal of your AoA
    1.4 Analysis Scope statement of information that will be studied
    1.5 Roles and Responsibilities List the roles and responsibility of all stakeholders involved in the project
    1.6 References List all guidance and Industry standards, or IRS requirements used for alternative analysis
    2.0 ANALYSIS FRAMEWORK  
    2.1 Analysis Approach Break the approach down to the smallest steps, all activities to accomplish, and add a process map or flowchart to illustrate.
    2.2 Assumptions/Constraints * Assumptions - Events that are expected to happen
    * Constraints - Limitations or restriction imposed on a project e.g., cost, schedule, resources, design, legal, quality, risk tolerance, ...etc
    2.2.1 Functional Assumptions/Constraints See explanation 2.2
    2.2.2 Product Assumptions/Constraints See explanation 2.2
    2.2.3 Cost Assumptions/Constraints See explanation 2.2
    2.3 Evaluation Criteria • Standard measures established to evaluate how the steps of the alternative solutions will meet the objectives or expectations.
    • Use weighted score cards for each alternative see IRM 2.5.4.4.2.
    2.3.1 Technical Assessment  
    2.3.1.1 Functional Requirements  
    2.3.1.2 System Requirements  
    2.3.1.3 Performance Requirements  
    2.3.1.4 Operational Requirements  
    2.3.1.5 Application Requirements  
    2.3.1.6 Cost Assessment Criterion  
    2.3.1.7 Risk Assessment Criterion Determine all risk, and what risks are acceptable
    2.3.1.8 Security Assessment Criterion  
    3.0 ALTERNATIVES  
    3.1 Alternative Identification  
    3.1.1 Alternative 1 Description  
    3.1.2 Alternative 2 Description  
    3.1.3 Alternative 3 Description  
    4.0 EVALUATION AND SCORING  
    4.1 Technical Assessment All technical information
    4.2 Cost Assessment  
    4.3 Risk Assessment  
    4.4 Schedule Assessment  
    4.5 Security Assessment  
    4.6. Evaluation Summary  
    APPENDIX A VENDOR PRODUCT CAPABILITIES  
    A1.0 Vendor Solutions/Responses to IRS organization comments  
    A1.1 Alternative Vendor 1 Description of Vendor/Contractor Responses
    A1. 2 Alternative Vendor 2 Description of Vendor/Contractor Responses
    A1.3 Alternative Vendor 3 Description of Vendor/Contractor Responses
    APPENDIX B LIST OF ACRONYMS  
    LIST OF FIGURES  
    LIST OF TABLES  

Weighted Scoring Method (WSM) - Non ELC

  1. 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:

    1. Prioritize alternatives to solve a problem

    2. Choosing a technological alternative

    3. Selecting a critical problem among several

    4. See table below for an example of weighted scoring

      Weighted Scoring Method (WSM) Example

      Requirements or Criteria Requirement Weight
      5 - High importance
      3 - Medium importance
      1 - Low importance
      0 - Does not satisfy
      Dell Monitor HP Monitor LG Monitor
        Note:
      1) Multiply each RequirementWeight row by each Alternative Score row.
      2) Add and total each weighted score column.
      Alternative Score Weighted Score Alternative Score Weighted Score Alternative Score Weighted Score
      Cost 4 ⇒ 4×3 ⇒ =12 4×5 ⇒ =20 4×1 ⇒ =4
      Design 1 ⇒ 1×5 ⇒ =5 1×1 ⇒ =1 1×5 ⇒ =5
      brightness 2 ⇒ 2×5 ⇒ =10 2×2 ⇒ =4 2×4 ⇒ =8
      Clarity 3 ⇒ 3×1 ⇒ =3 3×3 ⇒ =9 3×2 ⇒ =6
      Performance 5 ⇒ 5×1 ⇒ =5 5×0 ⇒ =0 5×3 ⇒ =15
      Total Weighted Score ⇒ N/A N/A 35 N/A 34 N/A ★38

       

  2. 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).

  3. Advantages of WSM:

    1. Provides a quick, easy and consistent method of evaluating your options

    2. Quantifies requirements and options with numeric values

    3. Facilitates agreement with stakeholders on priorities

    4. Establishes a common ground for the decisions making process

Proof of Concept (PoC) - Non ELC

  1. 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.

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

    • Validating technical feasibility may ensure the best version of your idea is achievable

    • Provide early Identification of any impediments

    • Prove to stakeholders their buy-in is worth the investment

Preparation - Proof of Concept (PoC)
  1. For software development, the entire design of the software must be explained in the documentation of your PoC. The documentation must include both functional and technical requirements. Some topics to consider are the following:

    • Security - The PoC must include a member area Graphical User Interface (GUI) if applicable

    • All necessary menus, tabs including search, home-page with logo, and the links for the sub-functions must be included

    • Dashboards User Interface (UI) if required

    • Include details of the architecture

    • All third party tools, all the technologies, and an explanation of the reasons for choosing the technology

    • All modules to be developed with a brief explanation of its functionality

    • Provide all methods used for ensuring the security of the project

    .

  2. For assistance with creating a Proof of Concept, contact the EA Front door at mailto:it.ad.front.door

Unified Work Request (UWR) - non ELC

  1. 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.

  2. 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 know 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.

  3. 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 (SLA), 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:

    1. Operations and Maintenance (Sustaining Infrastructure O&M): Maintaining Current Production Environment (CPE) for:
      • Break/Fix items
      • Routine maintenance

    2. Operations and Maintenance (Sustaining Infrastructure Rust): Refreshment process or replacement under the Asset Management policy for age.
      • Rust Replacement or replacing End of Life equipment

    3. Enhancement: A system enhancement of upgrades that increase the capabilities beyond the current approved system requirements for Current Production Environment (CPE). This request is not used to request new functionality.

  4. 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:

    1. Creating the work request and has the capability to open a request for another requestor contact.

    2. Adhering to internal work request policies and procedures established by requestor organization.

    3. Gathering information needed to prepare the work request.

    4. All high-level requirement/business needs, designs, processes and business rules are included in work request before submission.

    5. Requesting products or services from the IT organization by selecting a work request type for the product or service.

    6. Designating approver(s) for each work request in compliance with requesting organization standards.

    7. Serving as a subject matter expert or point-of-contact for business requirements.

    8. Responding to supplier request for additional information or requests for extensions relating to work requests.

    9. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡

  5. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡

  6. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡

Software Development Documentation Format Requirements

  1. 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:

    1. Organize your requirements in a hierarchical structure starting with the “Table of Contents”.

    2. Be consistent with imperatives, words like shall or must. whichever one is used, continue using it consistently across all requirements.

System-ID
  1. Assign a System-ID to each system. In the cases where the structured methodology is used, Information Technology specialists determine the scope of a system by the context diagram in the system’s Functional Specification Package (FSP).also known as the Simplified Design Specification Report (SDSR).

  2. The System-ID must appear in the page header, and serves to link the individual development documents.

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/SDSR 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 system diagrams, this information will appear in the title block of Form M–4327 or comparable form.

Page Size
  1. Page size considerations must lead to neat packaging of the document without sacrificing legibility. Reduce oversize pages to 8.5″ by 11" for final publication.

Page Numbering
  1. Each page must 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. When a specific type of documentation could be more advantageously numbered, choose the best method of numbering and insertion specific to the system.

Data Naming Standards
  1. The names of programs, modules, files, groups (including records), and items, must be in accordance with Data Naming Standards, see IRM 2.152.3 Information Technology, Data Engineering, Naming Data Element(s)/Object(s).

  2. All identifiers (names and numbers) must be consistent throughout the different types of documentation (Record Layouts, Computer Operations Handbooks, Application Descriptions, etc.).

General Rule

  1. Avoid redundancy in all applications documents.

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

Original Application Packaging Considerations

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

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

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

  4. Avoid duplication of record layouts, specifications, etc.

Preparation For Publication

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

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

    2. Section B. Additional Instructions—As a further explanation of Item 21, 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. Refer to system and organization specific instructions for this information.

Preparing Form 3210, Document Transmittal

  1. 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.

    1. Transmittal Number and Transmittal Dates - 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.

  2. 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

Document Version Control Standards

  1. Document version control is a way of ensuring all personnel involved know the current iteration of a document. This standard is very important for effective outcome of projects, and successfully status of your business objectives. Document versioning is also known as file versioning or file version management.

  2. For detailed document version control guidelines, see IRM 2.150.2.3.2 Information Technology, Configuration Management, Configuration Management Process, Document Versioning subsection.

Data Dictionary — Purpose

  1. The Data Dictionary (DD) i.e. metadata (database about a database) a data dictionary defines the structure of the database itself, but not the data held, and is used in control and maintenance of large databases. It is a central repository of information, and consists of the name, type, range of values, source, and authorization for access to each data element in the organization's files and databases. Additionally, it displays which application programs use the data so when a change in a data structure is expected, a list of affected programs can be generated. In the Design stage, the Data Dictionary is used for the following:

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

    2. Document all elements for a given system

    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.

Primary Project Repositories— IT Process Assets Library (IT PAL) and DocIT

  1. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡

  2. DocIT: The DocIT Project Library is a web-based electronic document management system powered by the enterprise standard tool "Documentum" . DocIT is the replacement system for Hummingbird DM, which was retired and shut down on February 29, 2008. The tool provides documentation control for IT projects. DocIT is an alternate repository for managing over half a million internal project documents within the IRS for over 4,000 customers. The system is administered by the Server Support and Services Division (SSSD) within Enterprise Operations (EOps).

    • During October 24, 2016, to comply with Personal Identity Verification (PIV) standards, the single-sign-on process was deployed for DocIT access eliminating the need of username and password login for registered end-users.. IRS employees without a DocIT user account must apply for an account via OL5081. Documents are uploaded 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.

    • As an alternate repository, artifacts produced during the Development phase can be retained as part of the project documentation in the DocIT Project Library, i.e. notes, memos, system changes, or quality review reports, along with any updates must be uploaded to the DocIT Project Library web site. See Exhibit 2.5.4-1 for a display of what artifacts are authorized for inclusion 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, if stored at an alternate IRS team storage repository.

System Description Documentation

  1. This documentation addresses the various components sometimes called modules of a software system. The components-level for system development represents the internal data structures and processing details of all the software components designed during architectural design.

System Description — Standard

  1. A System Description is required for each Information System.

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.

Contents and Organization

  1. 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.

  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 application streams

    • Number and type of applications/programs

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

    • On-line transaction processing capabilities and requirements

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

System Technical Design Diagram Documentation

  1. This documentation provides the generic information, contents, and organization for the system development diagrams.

System Technical Diagram — Standards

  1. 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.

System Technical Diagrams — Purpose

  1. 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.

  2. Technical diagrams provide:

    • Management and testing personnel with the general overview of the computer applications 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

    • The operations scheduler with a graphic representation for job set-up and operational procedures

System Technical Diagrams — Overview

  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 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.

  2. 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.

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

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

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

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

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

    1. Structural UML diagrams:
      Class Diagram: Class diagrams describe the static structure of a system.
      Package Diagram: Package diagrams are a subset of class diagrams, and organize elements of a system into related groups to minimize dependencies between packages.
      Object Diagram: Object diagrams describe the static structure of a system at a particular time, and can be used to test class diagrams for accuracy.

    2. Behavioral UML diagrams:
      Activity Diagram: Activity diagrams illustrate the dynamic aspects of a by modeling the flow of the control from activity to activity. An activity diagram presents a series of actions or flow of control in a system similar to a flowchart or data flow diagram, and can also describe the steps in a use case diagram.
      Use Case Diagram: Use case diagrams model the functionality of a system using actors and use cases. Use case diagrams are important for visualizing the functional requirements of a system that will translate into design choices and development priorities.

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

Technical Diagram Content and Organization

  1. Identify on each technical diagram:

    • Application / Program names

    • System runs/processes

    • Project Name

    • Terminal and intermediate files

    • Off-line system operations related to the applications

  2. 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.

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

  4. 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.

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

Preparing Technical Diagrams

  1. This subsection provides instructions for preparing a technical diagram. Technical diagrams

Application Numbers
  1. An application 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) = application or operation number. Allocate the "RR(R)" numbers to provide for subsequent insertion of other applications 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 application number sequences in a format different from the guidelines stated in this paragraph.

  2. If the application request is related to an application number previously issued, the analyst should review the information received as well as the application number data base to determine the new application number.

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

  4. The analyst must record the new application number on the application Number Registration Form.

  5. The analyst should provide the software developer the assigned application number via an electronic message.

File Numbers
  1. Assign a number to each file which appears on the Technical Diagram documentation. This number must be developed from the number of the application 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 is an optional feature.) Data set names are allowable if they provide more descriptive information.

    • SSS = System-ID

    • RR(R) = application 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 application 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).

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 applications and related off-line operations in an efficient sequence.

  3. Identify every input and output file (intermediate and terminal) for each application 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 technical diagram.

  7. A sample technical diagram is shown in Exhibit 2.5.4–6.

Terminal and Connector
  1. When an output file serves as input to two or more applications, identify that file with only one file number. Connect the output symbol to multiple applications with the appropriate terminal or connector symbols see Exhibit 2.5.4-4

  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 application, 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 application 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.

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

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

  3. Identify the processing frequency of the application or operation. The frequency is shown in the right center position of the application/Operation Box see Exhibit 2.5.4-5 and Exhibit 2.5.4-6 .

    1. Express frequency as follows:

      Example - Frequency of Application Operations

          Application     Operations      
      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 applications which have a specific application interval not represented by D, W, M, Q, S/A, A or O (e.g., bimonthly).

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

  4. List the application name in the lower portion of the Application/Operation Box. The name should relate to what the application accomplishes (e.g., Sort by Account Number, Sort and Edit, Translate, Merge, Convert PC to MT, Validate, Update).

Multiple Processes on Technical Diagram Documentation

  1. 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 Exhibit 2.5.4-1 for one way to show multiple processes.

  2. If the number of applications is so large that this method Exhibit 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.

Application Description (formally "Run" ) Documentation

  1. This subsection provides the generic information, contents, and organization for the application description.

Application Description — Standard

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

Application (formally "Run" ) Description — Purpose

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

Application Description (formally "Run" ) — Contents and Organization

  1. Each application Description will contain the:

    • Run name

    • Run synopsis

    • List of files accessed

    • Internal and external controls

  2. The Application Descriptions will be organized in application number sequence.

Preparing Application Descriptions

  1. This documentation provides instructions for preparing the application description.

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

  2. Identify the purpose of the application; that is, what it is intended to accomplish. List any pertinent facts about the application, such as externally called programs. If one application 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 applications and the corresponding processes (e.g., bubbles on the DFDs). When many levels of decomposition are encompassed by one application, only the highest level process which is uniquely identified needs to be referenced.

List of Files Accessed
  1. Prepare a list of the files which may be accessed by this application. Include both the file number and the file name. The list is divided into three parts: input files, output files, and I/O (input/output) files. Additional information may be included, such as "inquiry only " . This list is to include all files necessary to execute the application, such as print files, and application stream files.

  2. Describe briefly each output file produced by the application. Input files need only be described when they enter the system for the first time. Avoid redundancy by references to files that have already been described.

  3. Each description must contain:

    • File number;

    • Types of records contained in the file;

    • Manner in which records are batched, blocked, or grouped. Include a diagram when it is helpful; and

    • A statement about the sequence of records must be made, even when the file is in random order.

Internal and External Controls
  1. Describe the necessary controls, including any balancing instructions for utilizing the controls:

    • Internal Controls—any balancing schemes which have been developed to verify the validity of processing within an application.

    • External Controls—the information necessary for operations personnel to perform inter-application balancing, including which output file contains the control data, what control data are output, and to what element each item of control data should balance with.

Data Specification Documentation

  1. This specification provides the generic information, contents, and organization for data specifications.

Data Specification — Standard

  1. Data Specifications are required for each data structure.

Data Specification — Purpose

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

  2. Data structures are arranged hierarchically as follows:

    • Files : The physical, external interlaces between applications, each consisting of a set of related records

    • Records: A logical I/O (input/output) unit; e.g., the data referred to by a READ or WRITE instruction

    • Groups: A set of related items, defined together for convenience in manipulating as a unit (such as a date defined to be a group consisting of year, month, and day)

    • Item : An element or field; data which is not further decomposed

Data Specification — Contents and Organization

  1. The Data Specifications document will contain, in this order:

    • File descriptions/record layouts; and

    • Appendices, when necessary.

  2. 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.

  3. 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).

Preparing Data Specifications

  1. This documentation provides the instructions for preparing the data specifications.

Record Reference Numbers
  1. Assign a reference number to each record contained in a file shown on the technical documentation Diagram. This number is developed from the file number. An example of the format is "SSS-RR(R)-FF-NNN" where:

    • SSS = System-ID

    • RR(R) = application number

    • FF = file number

    • NNN = record reference suffix

  2. The record reference number serves as a cross-reference document. Therefore, only one record reference number will be assigned to a given record format see Exhibit 2.5.4-8.

  3. The record reference suffix "NNN" is not the same as the optional variable indicator "VVV" , which is added to a particular file number. The record reference suffix is used to form the record reference number which identifies individual record formats. The record reference number is only used in Data Specifications to distinguish records from one another. The "VVV" suffix, referred to above, will not be necessary in this case.

File Descriptions
  1. Describe the file briefly. Include any information about the file which is relevant, such as:

    • File name

    • File format

    • Manner in which records are batched, blocked or grouped

    • Access method

    • Sequence of records in the file (including random)

  2. Any other information describing the file may be included.

Record Layouts
  1. Each record layout will be prepared in a format similar to that shown in Exhibit 2.5.4–9. A record layout describes the structure of a record, showing its component groups and elements (items). The format may be developed manually, or tools such as a word processor or an automated Data Dictionary may be used.

  2. Record layouts will be prepared for all records contained in files identified in the technical documentation Diagrams. (If screen displays and printer layouts are developed in Analysis, do not repeat their definition in the record layouts.)

  3. All layouts must contain the following fields, regardless of the developmental method used:

    • Record name — as heading for the layout

    • Element numbers for the elements

    • Name — elements may be indented under a group name

    • Starting position — relative to the first position of the record

    • Length

    • Type (group, numeric item, alpha)

    • Remarks, including editing rules, valid ranges, etc., and separate or imbedded signs

  4. If the Automated Data Dictionary is used as a tool to aid in the definition of record structures, refer to the Data Dictionary section of this manual.

IBM Core Record Layout
  1. An IBM core record layout and IBM layout reference shall conform to the formats depicted in Exhibit 2.5.4-5, and must be developed using computer aided tools, e.g., electronic media, automated data dictionaries, spreadsheet programs, or other IRS authorized technologies.

  2. An IBM core record layout comprises a layout and, if required, a layout reference. The layout describes the structure, groups, and fields that constitute a record. Instructions for completing the IBM core record layout can be found in Exhibit 2.5.4-6.

Detailed Definitions
  1. The requirements mentioned for the System Description, System Technical documentation, Application Description, Data Specifications, and Computer Operations Handbooks are needed to define the physical data. This data must be documented in the Service-wide Data Dictionary.

  2. Regardless of the data type, the data details must be defined in a data dictionary repository. A suggested means for detailed definition is a local data dictionary that is either manual or automated. Although the local data dictionary is used to further describe the data, the requirement to update the Service-wide Data Dictionary still exists.

  3. Consistency is important. Do not introduce redundancy by repeating in the local data dictionary information that is already contained in the Service-wide Data Dictionary.

Computer Operations Handbooks (COH)

  1. This documentation provides consistent documentation for COH outlines, and is a required ELC project artifact after Project System Development phase for development and delivery within 90 days.

COH — IRS Standard

  1. 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 — Purpose

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

  2. 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.

COH — Data Item Description

  1. Arrange instructions in System—ID/Application number sequence.

  2. Document the computer operating instructions in accordance with the following standards and the instructions specified in Exhibit 2.5.4-11.

    1. Assemble the operating instructions for each application as a complete set.

    2. Place operating steps in the proper sequence and cross-reference steps when applicable.

    3. When an application contains options, document with separate operating instructions for each option.

    4. Only one set of operating instructions are to be provided for programs which only differ by their file contents.

COH — Forms

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

  2. Examples of forms, which are to be used in compiling the Computer Operations Handbook, are shown in Exhibits Exhibit 2.5.4-11 These examples include the following forms:

    COH Operating Instruction Forms

    Form
    Number
    Form
    Title
    IR-3864 I/O UNITS
    IR-3864–A SET-UP INSTRUCTIONS OPERATING INSTRUCTIONS
    IR-3864–D MESSAGE LIST OPERATING INSTRUCTIONS

     

  3. 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.

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

COH — Language Considerations

  1. Use language that is clear and concise.

  2. 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.

  3. Avoid excessive abbreviations to insure readability.

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

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

COH - Title Page Template

  1. COH title page must consist of the information below:

    1. Project Name

    2. Title Name

    3. Document ID

    4. Document Version Number

    5. Document Effective Date

    6. Prepared for: - Insert the agency name

    7. Contract Number

    8. Task Order Number

  2. For more information see table below:

    COH Title Page Template

    Example - COH Title Page Template
    Project Name

    Computer Operations Handbook

    Document ID: <Insert unique reference number>

    Version Number:

    Effective Date: <MM/DD/YYYY>

    Prepared For:
    AGENCY NAME:

    Contract Number:

    Task Order Number:

     

     

COH - Standard Header and Footer Information

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

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

    1. Application Title

    2. Followed by Computer Operator Handbook

    .

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

    1. Application: An Application, formerly known as run or command code in "PPP-RR" format where "PPP" equals the project and "RR" equals the run.

    2. Title: One line description of the application (formerly known as run or command code).

    3. Page Number: The physical page number.

    4. System ID: The first two digits of the system ID.

COH — Paging

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

  2. Enter the page number on each page.

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

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

    • I/O Units

    • Set-Up Instructions

    • Message List

  5. 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.

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

COH Standard Outline

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

  2. ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡ ≡≡ ≡

Operator Messages

  1. Keep operator queries or messages to a minimum.

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

  3. Information messages should appear on the printed listing only.

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

  5. 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.

IBM COH Guide

  1. 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.

  2. 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.

Sample System Description Outline

SYSTEM NAME:      
SYSTEM ID:     OPERATIONAL DATE:
RESPONSIBLE ORG:     REVISION DATE:
       
  SYSTEM DESCRIPTION  
       
  A. General Description  
  1. Scope  
  2. Background  
  3. External Interfaces  
  B. Operating Environment  
  1. Equipment  
  2. Controls  
  3. Security/Privacy Requirements
  4. Failure Contingencies
  C. Applications / Programs  
  1. Number and Type  
  2. Optional Application Streams
  3. Data Base Characteristics
  D. Miscellaneous  

Technical Diagram Documentation—Title Block

Technical Diagram Documentation.   The following instructions are keyed to the illustration below:
Key Item Instructions
A Title The words "Technical Diagram(s)" must appear on each page, followed by a descriptive title, such as "SC Daily Processing" .
B Issued by The organizational symbols of the originating office will appear here.
C Date Enter the operational date of the system.
D Revisions No.— The number of the revision, beginning with one ("1" ).
    By — Enter the transmittal number assigned to the revision.
    Date — Date of the transmittal.

Sample Data Specifications

Example of Data Specifications
SYSTEM NAME:     OPERATIONAL DATE:
SYSTEM ID:     REVISION DATE:
RESPONSIBLE ORG.:      
  DATA SPECIFICATIONS
  1. FILE NAME:
  2. FILE NUMBER:
  3. FILE FORMAT:
  4. MEDIA:
  5. ORGANIZATION:
  6. ACCESS METHOD:
  7. BLOCKING FACTOR:
  8. NUMBER OF RECORD TYPES:
  9. LABELS:
NOTES:

File and Record Index (Instructions)

1. List the file numbers of all the files related to a given system. These files will be listed in ascending sequence based on file number.

2. Within the above list, list the records contained in each file, in ascending sequence by record reference number. The record reference number serves as a cross-reference to the record layouts in this document; therefore, only one record reference number will be assigned to a given record format. For example:

System File Number and Reference Record Number

File Number Record Reference Number
7600101 7600101–001
7600101–002
(repeat until all records for file 7600101 are listed)
7770101 7770101–001

 

3. Enter the record name for each record reference number listed.

4. Enter the file name for each file number listed.

5. Enter the block size established for each file.

6. Enter the maximum record length for each record.

7. Enter the file format as follows:

File Format Standards

File Format Standards
File Block Format
F—Fixed
FB—Fixed Blocked
V—Variable
VB—Variable Blocked

 

1. For tape files, enter the tape density (e.g., compressed files of 18 and 36 tracks).

2. If the file is a disk file, enter the word "DISK" . For tape files, enter the tape characteristic; e.g., "9" for 9 track tapes.

3. Enter the number of days a file must be retained.

Master Record Layout

  EMPLOYEE-MASTER-RECORD        
Element Number Name Start Pos Length Type Remarks
1 EMPLOYEE-CODE l 4 Num  
2 EMPLOYEE-IDENTIFICATION 5 111 Group  
3 SOCIAL-SECURITY-CODE 5 9 Num SSN
4 EMPLOYEE-NAME 14 30 Char Last name first
5 STREET-ADDRESS 44 30 Char  
6 CITY 74 25 Char  
7 STATE 99 2 Alpha Standard abbreviation
8 ZIP-CODE 101 5 Num  
9 TELEPHONE-NUMBER 106 10 Num Include area code

Instructions for Completing the IBM Core Record Layout

The IBM core record layout specifies the following fields:
  a) Element Name — The name of the elements that constitute a record layout. Elements may be indented under a group name ( begin group element names with a hyphen).
  b) Dec — The displacement in decimal. If this field does not apply, then it may be left blank.
  c) Hex — The displacement in hexadecimal. If this field does not apply, then it may be left blank. (The hexadecimal displacement does not show decimal points.)
  d) Length — The length of the field (designate 1/2 byte fields as 0.5).
  e) Type — This item indicates the data format of the element (e.g., packed decimal, zoned decimal, funny packed, character) and the number of decimal positions and sign.
  f) Ref — This item indicates the reference number (number sequentially beginning with 1) or whether a reference entry exists for the field (indicate with a "Y" ). Use a reference for lengthy remarks, otherwise leave this item blank. The references should be on a separate page at the end of the layout.
  g) Remarks — This item identifies additional information regarding the element such as editing rules and valid ranges. It may also be used for short remarks (one to a few lines).
   

Note:

It is not necessary to specify in the remarks YYYYMMDD for date fields, YYYYMM for tax periods or YYYYCC for posting cycle since these are the IRS standards. However, if a date element is in month-day year format, then MMDDYYYY should be entered in the remarks since this is nonstandard.

  h) * — This item identifies elements that have been updated. Possible values are "I" (Insert — new field, record expands), "R" (Replace — field replaced or renamed), "M" (Move — field repositioned within record), and "C" (Change — field size changes, record expands/contracts).
The file name, record name (title) and date constitute the heading and must be displayed on each page.
Each record must end with the element "Total Record Length." On variable records indicate a minimum and maximum length (if available).
If additional space is required for remarks regarding fields specified in the layout, then use an IBM Layout Reference.

Instructions for Completing Form 3864—I/O Units

1. The I/O Units page must contain all data files necessary to execute the application being documented (e.g. catalogued, temporary special print processor files, etc.). For each file, the device file type, number and name used by the program being documented must be specified. Any specific conditions concerning the file translation or special device options must also be indicated. Program application options that include or exclude certain files must be mentioned under the conditions portion of the I/O Units page.

Space Title Instructions
1. SYSTEM-ID/Application NUMBER (1) Identify the program by System-ID and application number in the format SSS-RR(R).
(2) When there are options involved in a single application and each option is documented on a separate page, identify the option by SSS-RR(R).n (where n = option number).
2. FILE ASSN. System-specific
3. DEVICE System-specific
4. FILE NUMBER (1) Enter the file number in the acceptable standard format. File numbers must be consistent with the ANSI File Header Label and any End-of-File Label for tape.

Note:

This must also correspond to the file numbers on the technical diagrams documentation.


(2) Input files are to be listed first in ascending file number sequence. These will be followed by output files also listed in ascending file number sequence.

Note:

Files that serve as both input and output should be integrated in the list of input files according to the specified sequence and not repeated in the list of output files.


(3) Make no entry here if a tape is used as a work tape; such as a checkpoint file. This type of information is contained in CONDITIONS.
5. FILE NAME Enter the name of the file identified by the file number in space 4. This identifier must be consistent with the technical diagrams documentation.
6. I/O Identify: I = Input Unit I/O = Input and Output (in the same application).
O = Output Unit
List all Input Units first, Input/Output Units second and Output Units last.
7. CONDITIONS Note any special restrictions on the file or unit. When the space provided is not adequate, cross reference the appropriate step in the Set-Up Instructions. All application options affecting file assignments must be listed under CONDITIONS, and cross referenced in the Set-Up Instructions.
8. EFFECTIVE DATE/CYCLE Identifies when the current information contained on this page becomes operational. (TRANSMITTAL NUMBER AND DATE may be substituted for the EFFECTIVE DATE/CYCLE.)
9. PAGE NUMBER Enter the page number of the pages for this application.
10. COMPUTER AND SIZE Identify the computer by name and number.
11. Application TITLE Enter a brief title for application identification that is consistent with the application description and technical diagrams.
12. SYSTEM-ID/Application NUMBER Identify the System-ID and application number as entered in space 1.

Instructions for Completing Form 3864A—Set Up

Space Title Instructions
1. SYSTEM-ID/APPLICATION NUMBER (1) Identify the System-ID and application number in the format SSS-RR(R).
(2) When there are options involved in a single application and each option is documented on a separate page, identify the option by SSSRR(R).n (where n = option number).
2. STEP NO. Number each step in unbroken sequence beginning with 1.
3. INSTRUCTIONS Provide the necessary instruction, using imperative sentences, needed by the operator to set up the application as follows:
(1) Include set-up steps for the job control language/executive control language (JCL/ECL — program, data, and control), the printer, disk unit, etc.
(2) When JCL/ECL statements, data cards or other special data cards are necessary in the job set up, provide a list of the statements or cards.
(3) Include complete, precise instructions and illustrations regarding the set-up of Checkpoint/Restart packets. It is recommended that this be a separate and unique set-up page.
(4) Reapplication and restart procedures must be addressed for each application. If there are no special restart procedures this should be stated. A separate page containing reapplication instructions must be included for each application. Precise information concerning file manipulation (delete, reload, or recatalog), and other pertinent instructions for the operator must be included on this page. If an alternate application stream is necessary to reapplication a job, this must be listed and documented in the same fashion as all other application streams. If no special instructions are required for a particular application, this should be stated with a reference to the appropriate first-time application instructions. Programs that access a data base must have reapplication and restart instructions. Include information such as whether a data base area must be reloaded to eliminate updated records prior to reapplication.
(5) When a controlling device is required for any I/O unit; e.g., printer carriage control tape, be sure to identify it by name and, when available, identification number. Include all application specifications.
(6) When there are options involved in one application, separate them into sets of loading steps accordingly. Begin each set on a new page. State the option number followed by option name on one line; e.g., OPTION 2. Monthly Tables. When necessary, include a two or three sentence synopsis of option. List the steps of the option sequentially beginning with 1.
4. EFFECTIVE DATE/CYCLE Identifies when the current information contained on this page becomes operational. (TRANSMITTAL NUMBER AND DATE may be substituted for the EFFECTIVE DATE/CYCLE.)
5. PAGE NUMBER Enter the page number of the pages for this application.
6. COMPUTER AND SIZE Identify the computer by name and number.
7. Application TITLE Enter a brief title for application identification that is consistent with the application description and technical diagrams.
8. SYSTEM-ID/Application NUMBER Identify the System-ID and application number as entered in space 1.

Instructions for Completing Form 3864D—Message List

Space Title Instructions
1. SYSTEM-ID/APPLICATION NUMBER Identify the System-ID and application number in the format SSS-RR(R).
2. NUMBER Number each message in an unbroken sequence beginning with 1. List all messages whether computer processing continues or not.
3. MESSAGE (1) All program generated messages must be listed on the Message List Operating Instructions. All messages must be documented, and those that are not self-explanatory must have clear, concise instructions. If the message is informational only, this should be stated under the EXPLANATION column. It is recommended that messages be separated into two categories: CONSOLE MESSAGES and INFORMATION MESSAGES (those appearing on the printed listing only). Discretion must be used in deciding which messages go where. Only those messages which require operator intervention or affect the continued operation of a application stream should appear on the console. All other messages should be routed to the application control print log (if available). 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.
(2) Enter any fixed message by writing it in capital letters; e.g., "EOJ" . In a variable message, indicate the variable part with lower case letters; e.g., mm-dd-yyyy for a date or nnnn for a displayed number.
4. EXPLANATION AND OPERATOR ACTION If the message requires any operator action, explain in detail what the operator is to do. If there is no required action, state "No operator action" . Give any explanation or clarification of the message which will aid the operator.
5. EFFECTIVE DATE/CYCLE Identifies when the current information contained on this page becomes operational. (TRANSMITTAL NUMBER AND DATE may be substituted for the EFFECTIVE DATE/CYCLE.)
6. PAGE NUMBER Enter the page number of the page for this application.
7. COMPUTER AND SIZE Identify the computer by name and number.
8. APPLICATION TITLE Enter a title for the application identification that is consistent with the application Description and technical documentation Diagrams.
9. SYSTEM-ID/ APPLICATION NUMBER Identify the System-ID and application number as entered in space 1.

Instructions for Completing the IBM COH Guide

Completing the IBM COH Guide
Purpose — The IBM Computer Operations Handbook (COH) Guide is required before processing and provides detailed instructions to a computer operator for the proper execution and validation of an application or program. It also provides the conventions and standards applicable to all IRS developers, and is a required deliverable for the programming stage of development. This guide is applicable to the IBM Tier 1 mainframe (except the Automated Collection System), and applies to all developers engaged in the development of IBM or IBM-compatible programs.
Scope — The information presented in this manual covers the IBM COH Guide, and is composed of information from the previously used IBM Computer Operations Handbooks (such as the I/O Units), application description, technical documentations, and file specifications as described in this guideline. The instructions in this exhibit offer guidance in completing Exhibit 2.5.4–20, IBM COH Guide.
1. Application/Command Code: The actual command code or application in PPP-RR format where PPP equals the project and RR equals the application. The Integrated Collection System (ICS) format may vary from six to eight alphanumeric characters.
2. Title: A one line description of the application or command code.
3. Page Number: The physical page number as if the document was printed on a 8 1/2″ by 11″ inch sheet of paper.
4. Section-ID: The first two digits of your user ID.
1. Application Description: A short paragraph describing what this application or command code accomplishes.
2. Frequency: The number of times this project is executed in a given year. Valid responses are: daily, weekly, monthly, bi-weekly, bi-monthly, annually, bi-annually, once, etc.
3. System Resource Requirements: The number and type of input drives, output drives, Disk Requirements, or DB2/CICS/Teradata needed. Valid media types are: Bosch, STK, Optical, DASD, CART8, CART36, Tape9, Memorex ATL, etc. Indicate if the job updates or has exclusive access to a database (or is read only).
4. Sort/Merge Fields: A list containing the order of the output. Ignore this field if the program is not a sort or merge and the files are already in order.
5. Changes Included: Explanations for the changes should be specific, relevant, and easy to understand. When changes do occur, transmit a completely new IBM COH Guide to replace all prior transmittals.
 
1. Technical Diagram Documentation Location: Provides the technical document diagram location in IT PAL. This would be a single application or the first application in a series of applications.
2. MCC Cycle Designation: The cycle designation received from MCC schedulers. Valid responses are: BEW-, BEM-B, IPW-P, IEX-A, etc. For MCC purposes, put the cycle designation in the reference field on the technical diagram document profile.
 
1. Job Step: This indicates a job step's association with the system resource requirements and I/O elements (ICS).
2. DDNAME: The DDNAME from the JCL that is associated with this file.
3. File Name & DSN: The complete data set name and a short description of the file.
4. Unit: From the Unit parameter of the JCL.
5. Label: From the Label parameter of the JCL. Not applicable for disk datasets.
6. Ret: The retention in days required to keep this file. This is not applicable for input files.
7. CRL: The Core Record Layout Reference Number; in order to access the CRL, go into IT PAL and enter the application.
8. TO: The major application or final destination to receive this file, if appropriate. This is not applicable for input files.
9. BLKSIZE: Block size concerns how the records are transmitted and stored on an I/O device. Include block size, if appropriate.
10. PRINT OPTION: Furnish the appropriate information, including the logical record length (LRECL) if necessary.
 
1. Special Cards: The layout of any special cards, in the order that is required by the program, which also includes a short explanation. The CP23 or CP2000 cards should be included if needed. State if the program utilizes the CP23 or CP2000 macros if that is true. The DD name should be included if it is other than SYSIN.
2. Rerun/Restart Requirements: Any rerun application or restart requirements. Indicate any disk file that needs to be set back, e.g., to a previous time period or with a generation data group.
3. Special Considerations: Any additional information that would help Scheduling, Production Control, or Operations run your job correctly the first time or how to restart it smoothly. Include any date considerations, e.g., on setup cards. Explain the PARM values on the EXEC card, if appropriate.
 
1. Job Step: This indicates which job step created the message (ICS).
2. Number: This must be the halt or abend codes so that the operators can research the abend code. When it is a message for information only, not requiring a reply, it can be just a sequential number of messages relative to the order of appearance.
3. Message Text: The actual text in the message.
4. Explanation: A short explanation as to why the message was sent.
5. Action/No Action: Any expected action by Scheduling, Production Control, Operations, or RPA/CSA personnel. "No Action" is also a valid response.
6. Restart Instructions: This must include any special instructions for Production Control, Operations or RPA/CSA personnel.
 
1. LARS Balancing Equations: The LARS formula as it will appear.
2. Explanations: A paragraph explaining what the balancing instruction is trying to accomplish and how to manually balance if a LOOB is received.
3. Counters: All single record counts, record count arrays, single money amounts, money amount arrays and explanations should be listed. LARS CNTL001 messages are needed in the balancing instructions along with the file number associated with each LARS counter. Also, a TOTAL line is required when more than one (1) pass is involved.
4. Manual Balancing: If the program does not contain any LARS Balancing instructions it will be necessary to explain how the Processing Validation personnel will be able to verify the record counts or money amounts received.
5. External Counters: If the records received are from an outside agency, one should include the number of records on the input and which counter it is equal to in the program, if appropriate.
6. Auto Control Records (from external to center): If control records are included with the data records they should be described here, if appropriate.

IBM COH Guide

Standard Information — To be included on each printable page.
1. Application/Command Code 2. Title 3. Page Number
PPP-RR (except ICS)
4. Section-ID
Section I — Application Description and Nature of Changes
1. Application Description:
2. Frequency:
3. System Resource Requirements 4. Input Drives:
  5. Output Drives:
  6. Disk Requirements:
  7. DB2/CICS/Teradata:
8. Sort/Merge Fields:
9. Changes Included:
Section II — Technical Diagram
1. Technical Diagram Location:
2. MCC Cycle Designation:
Section III — I/O Page
1. DDNAME 2. FILE NAME & DSN 3. UNIT LABEL 4. RET 5. CRL 6. TO
7. JOB STEP (ICS) 8. BLKSIZE: 9. PRINT OPTION:
Standard Information — To be included on each printable page.
1. Application/Command Code 2. Title 3. Page Number
  • PPP-RR (except ICS)

4. Section-ID
Section IV — Setup Cards/Sysin Cards
1. Special Cards (explanation & sequence):  
  2. DD Statement (Sysin or other):
  3. Cards formatted (in required order):
 
  1. CP23/CP2000 card or

  2. CP23/CP2000 macro utilized or other options

5. Reapplication/Restart Requirements:
6. Special Considerations:
Section V — Halts/Messages/User Abends
1. Job Step 2. Number 3. Message Text 4. Explanation 5. Action/ 6. Restart Instructions
7. (ICS)       8. No Action  
Section VI — Balancing
1 LARS Balancing Equations:
2. Explanations:
3. Counters:
4. Manual Balancing:
5. External Counters:
6. Auto Control Records (from external to center):

Acronyms and Terms

ACIO Associate Chief Information Officer
AoA Analysis of Alternative
BSR Business Systems Report
CICS Customer Information Control System
CRL Control Record Layout
COH Computer Operator Handbook
CPB Computer Program Book
CSA Computer Systems Analyst
ECL Executive Control Language
ELC Enterprise Life Cycle
DSP Design Specification Package
DSR Design Specification Report
FSP Functional Specification Package
ICD Interface Control Document
ICS Integrated Collection System
IBM International Business Machine
I/O Input/Output
ISO International Standards Organization
IEEE International Electrical and Electronics Engineers Standards Association
JCL Job Control Language
LARS Log Analysis and Reporting System
LDD Logical Design Description Document
MS Milestone
NIST National Institute Standards and Technology
PCLIA Privacy Civil Liberty Impact Assessment
PD Process Description
PRP Program Requirements Package
RPA Resident Programmer Analyst
SEI Software Engineering Institute
SD System Description
SDLC System Development Life Cycle
SDSR Simplified Design Specification Report
SRR System Requirements Review
SRR System Requirements Report
SSP System Security Plan
UWR Unified Work Request
VSA Vision Scope and Architecture

Terms and Descriptions

Agile A time boxed, iterative approach to software delivery that builds software incrementally from the start of the project.
Application Any program or group of programs designed to perform a specific function for the end-user or another application program.
Artifact Documents that a program/project must produce for each phase of the SDLC
Enterprise Life Cycle ELC is a project lifecycle management methodology equivalent to an industry version of System Development Life Cycle
Functional Specification Package Formal document that details all features and specifications of a certain software product. during the Requirements phase of the software development process
Milestone Task of zero duration that displays an important achievement in a project
Process Owner Person who has the authority to determine how a process operates, and the responsibility to make sure if continues to meet the customer standards and business needs.
Proof of Concept Documented evidence that a potential product or service can be successful
System Development Life Cycle A project management model that defines the stages involved in bringing a project successfully from initiation to completion. phases are planning, system analysis, system design, development, integration and testing, and operations and maintenance
System Requirements Review Conducted to evaluate the completeness, consistency, and achievability of the requirements necessary to meet the mission, project, operations, system and subsystem
Vision Scope and Architecture DID Provide by reference to authoritative repositories, confirmation that the necessary project scope and architecture have been sufficiently bounded and characterized to begin design and development within acceptable risk.

Project Charter Content

Charter Sections Recommendations for Sections 2 - 9.
Title Page  
Approvals page  
1. Introduction  
1.1 Purpose  
1.2. Document Maintenance  
1.3 Document Distribution  
2. References List the current EA version for the charter and program documents.
3. Stakeholders List all personnel involved with the work or provides approvals for the project.
4. Governance Provide a statement of intent that mandate principles or standards that apply to IRS operations or practice.
5. Problem Statement Describe the problem statement with project objectives and the summarized details.
6. Project Objectives Include all related project goals.
7. Assumptions, Constraints, Exclusions, and Dependencies Review all constraints, like integration with COTS and other dependencies.
8. Business and Technical Scope from the Enterprise Architecture • Contains both business and technical components:
Business components include:
* Business Processes
* Organization, Location
* Enterprise Conceptual Business Service
Technical components include:
* Functional Requirements
* System Interfaces
* Transitional Systems
* Target Releases
* Enterprise Transition Plan
* Enterprise Standards Profile
9. Proposed Release Plan Compare the release plan and scope of the project to ensure they are consistent.
Appendix A: Glossary  
Appendix B: Acronyms  

Enterprise Architecture - Interactive ELC Artifact By Phase Chart

Interactive ELC Artifact By Phase Chart  
MILESTONES MS 1 MS 2 MS 3 MS 4A MS 4B MS 5  
PHASES PROJECT INITIATION DOMAIN ARCHITECTURE PRELIMINARY DESIGN DETAILED DESIGN SYSTEM DEVELOPMENT SYSTEM DEPLOYMENT O&M
  FUNCTIONAL BASELINE ALLOCATED BASELINE PRODUCT BASELINE OPERATIONS & MAINTENANCE
  Logical Design Physical Design
  • Project Tailoring Plan (PTP) • PTP update as needed PTP update as needed PTP update as needed PTP update as needed  
  • Project Charter   CIS Chart – Logical (What) CIS Chart – Physical (How)  
  • Automated Project Management Plan (aPMP)2 • aPMP2 update as needed • aPMP2 update as needed • aPMP2 update as needed •aPMP2 update as needed • aPMP2 update as needed
  • Configuration Management Plan (CMP)3 • CMP3 update as needed • CM Worksheet – Logical (What) • CM Worksheet – Physical (How)    
Configuration Management (CM) Baselines Security Package (SP)4 • SP4 update as needed • SP4 update as needed ·• SP4 update as needed • SP4 update as needed • SP4 update as needed
  • Privacy Package / Privacy and Civil Liberties Impact Assessment (PCLIA) • PCLIA update as needed • PCLIA update as needed • PCLIA update as needed • PCLIA update as needed • PCLIA update as needed
  • 508 Accessibility and Mitigation Package 5 • 5085 update as needed • 5085 update as needed • 5085 update as needed • 5085 update as needed • 5085 update as needed
  • Enterprise Organizational Readiness (EOR) Service Request • Enterprise Organizational Readiness (EOR) Workbook • EOR Workbook update as needed • EOR Workbook update as needed • EOR Workbook update as needed  
  • Lessons Learned Review • Lessons Learned Report (LLR) • LLR update as needed • LLR update as needed • LLR update as needed • Final LLR
    • Business System Report (BSR) • BSR update as needed • BSR update as needed • BSR update as needed  
  • REPO Standard Requirements Repository • REPO Standard Requirements Repository update as needed • REPO Standard Requirements Repository update as needed • REPO Standard Requirements Repository update as needed
  • Development/Unit Test Government Equipment List (GEL) if needed • Enterprise Integration & Test Environment (EITE) GEL if needed • Production GEL if needed • Production GEL if needed
  • System Deployment Plan (SDP) • SDP update as needed • SDP update as needed • SDP update as needed
        • Simplified Design Specification Report (SDSR)6 • Simplified Design Specification Report (SDSR) 6 update as needed  
• C&L Questionnaire
        • Interface Control Document (ICD) • ICD update as needed • ICD update as needed
        • System Test Plan (STP)6 • STP6 update as needed • STP6 update as needed
          • User Doc & Training Materials: The Process Owner is the Project Customer: The End User Organization that is receiving the system
        • Computer Operator's Handbook (COH) • COH update as needed
           
• End of Test Completion Reports (EoTCR) 6, 7
         
 
The ELC Project Ends upon successfully completing Phase 5

Example - Computer Operations Handbook Outline

Computer Operations Handbook Outline
1. Introduction
1.1 Purpose
1.2 Identification
1.3 Document Organization
1.4 Document Maintenance
1.5 References
2. Description and Nature of Changes
2.1 Changes Included
3. Architecture and Infrastructure
3.1 Application/System Overview
3.2 Architecture
3.3 Infrastructure
4. Application Execute/Run
4.1 Setup Instructions
4.2 Out-of-Balance Events
4.3 Error Correct/Problem Resolution
5. Operate and Maintain
5.1 Backup/Restore
5.2 Disaster Recover (DR) Plan
5.3 Performance Monitoring
5.4 Incident Management
5.5 Maintain
5.6 Update/Patch Management
6. Performance & Capacity Planning
6.1 Transactions
6.2 Data Volumes
6.3 Users/Hours of Operations
Appendices
Appendix A: Abbreviations and Acronyms
Appendix B: Master Contact List
Appendix C: COH Creation Checklist

Example - Business System Report Template

Example - Business System Report Template
TITLE page with IRS Logo
SIGNATURE APPROVAL page
DOCUMENT MODIFICATION HISTORY page
TABLE OF CONTENTS page
Section 1. INTRODUCTION
1.1 Purpose
1.2 Scope
1.3 Methodology
1.4 Document Maintenance
Section 2. References
Section 3 Business System Concept Description
3.1 Business Drivers and Objectives
3.1.1 Business Drivers
3.1.2 Business Objectives
3.2 Current State Description
3.2.1 Current State Characterization
3.2.2 Current State Weaknesses and Opportunism
3.2.3 Current State Metric
3.3. Future State Description
3.3.1 Future State Vision and System Context
3.3 2 Business Events
3.3.3 Benefits
3.3.4 Capabilities
3.3.5 Measures
3.3.6 Scope of Business System Impact
3.3.7 Principles, Constraints and Assumptions
3.3.8 Critical Success Factors
3.4. Solution Concept
3.4.1 Solution Concept Description
3.4.2 External Interfaces
3.4.3 Existing Systems and Services to be Leveraged
3.5. Solution Concept Approach and Rationale
3.6. Stakeholders
3.7. Risks, Issues, and Solution Strategies
Section 4. Releases
4.1 Summary of Release Strategy and Rationale
4.2 Defined Releases
Section 5. Business Architecture
5.1 Key Business Architecture Constraints and Assumptions
5.2 Business Process Architecture
5.2.1 Business Process Model
5.2.2 Changes to Current State and Their Impacts
5.2.3 EA Traceability
5.3 Business Rule Sets
5.3.1 Business Rule Description
5.3.2 Changes to Current State and Their Impacts
5.4 Business Rule Rules
5.5 Term Catalog
5.6 Organizational Changes
5.6.1 Changes to Current State and Their Impacts
5.6.2 EA Traceability
5.7 Location Changes
5.7.1 Changes to Current State and Their Impacts
5.7.2 EA Traceability
5.8 Business Architecture Inter-Relationships
5.9 Business Risks, Issues and Solution Alternatives
Section 6. System Architecture
6.1 System Use Cases
6.2 Secondary Use Cases
6.3 Sequence Diagrams
6.4 System Use Case Traceability
Section 7. Infrastructure Architecture
7.1 Key Technology/Infrastructure Constraints and Assumption
7.2 Infrastructure Functional Architecture
7.3 Interfaces
7.4 New Technology/Infrastructure Services to be Provided
7.5 Possible Alternatives for Providing These New Services
7.6 Changes to Current State and Their Impacts
7.7 Technology Infrastructure Risks, Issues, and Solution Alternatives
7.8 Traceability
Section 8. Application Architecture
8.1 Key Application Architecture Constraints and Assumption
8.2 Application Use Cases
8.3 Application Functional Architecture
8.4 Potential Solution Alternatives
8.5 Changes to Current State and Their Impacts
8.6 Application Risks, Issues and Solution Alternatives
8.7 Traceability
Section 9. Data Architecture
9.1 Key Data Architecture Constraints and Assumption
9.2 Conceptual Data Model
9.3 Additional Data Related Functionality
9.4 Changes to Current State and Their Impacts
9.5 Data Migration Plan
9.6 Data Risks, Issues and Solution Alternatives
9.7 Traceability
Section 10. Security Architecture
10.1 System Security Categorization
10.2 Security Constraints and Assumption
10.3 Threat Analysis
10.3.1 System Threat and Vulnerability Identification
10.4 Data and Interface Security Characteristics
10.5 Definition and Allocation of Baseline Security Controls
10.6 System Security Dependencies
10.7 Existing System Analysis
Section 11. Nonfunctional Considerations
11.1 Performance
11.1.1 Business Performance
11.1.2 Technical Performance
11.2 Capacity Considerations
11.3 Accountability Considerations
11.4 Availability Considerations
11.5 System Installation, Operational, Maintenance and Support Considerations
11.5.1 System Installation Considerations
11.5.2 Maintenance Considerations
11.5.3 Support Considerations
11.6 System Disposal Considerations
11.7 Disaster Recovery Considerations
11.8 Privacy Considerations
Section 12. Development Environment Considerations
Section 13. Business System Requirements Description
13.1 Program Requirements
13.2 Reusable Program Level Requirements
13.2.1 Custodial Financial Requirements
13.2.2 Disaster Recovery Requirements
13.2.3 Infrastructure-Related Requirements
13.2.4 Operation Related Requirements
13.2.5 Privacy Requirements
13.3 Requirements
13.3.1 Business Requirements
13.3.2 Functional Requirements
13.3.3 Non-Functional Requirements
13.3.4 Non-Categorized Requirements
13.4 Traceability
Section 14. Verification and Validation
Acronyms
Glossary
Appendix A - Alternative Architectures Considered
Appendix B - Business Rules
Appendix C - Term Catalog
Appendix D- Security Controls
List of Figures and Tables

Vision Scope and Architecture (VSA) Document Components

Example - Vision Scope and Architecture Document Format
TITLE PAGE WITH IRS LOGO
SIGNATURE APPROVAL Page
DOCUMENT MODIFICATION HISTORY page
TABLE OF CONTENTS page
Section 1. INTRODUCTION
1.1 Purpose
1.2 VSA Scope
1.3 Vision, Scope and Architecture Organization
1.4 VSA Maintenance
1.4.1 Maintenance of VSA Artifacts and Traceability
1.5 VSA Distribution
Section 2 REFERENCES
Section 3. VISION
3.1 Purpose and Objectives
3.2 Future State Vision
3.3 Measures
Section 4. SCOPE
4.1 Epics/Capabilities
4.2 Epics/Capabilities Decomposition
4.2.1 Functional
4.2.2 Non-Functional
4.2.3 Enterprise Requirements Allocations, including Reusable Program Level Requirements (RPLRS)
4.3 Enterprise Architecture Allocations
4.4 System Boundary and High Level Flow
4.4.1 System Context
4.5 Principles, Constraints and Assumptions
4.6 Risks and Solution Strategies
Section 5. SYSTEM ARCHITECTURE
5.1 System Architecture Rationale and Alternatives Analysis
5.2 System Architecture
5.3 Common Services
5.4 Infrastructure Architecture
5.5 Application Architecture
5.6 Data Architecture
5.7 Security Architecture
5.7.1 System Security Categorization
5.7.2 System Threat and Vulnerability Analysis
5.7.3 Allocation of Secularity Controls
5.7.4 Privacy
5.7.5 Existing System Analysis
5.8 Development Environment
Appendix A - Acronyms and Glossary
List Of Figures And Tables

FSP/SDSR Standard Document Components

Example - FSP/SDSR Standard Document template
TITLE PAGE WITH IRS LOGO
SIGNATURE APPROVAL Page
DOCUMENT MODIFICATION HISTORY page
TABLE OF CONTENTS page
Section 1. INTRODUCTION
1.1 Purpose
1.2 Scope
1.3 Document Organization
1.4 Document Maintenance
1.5 Document Distribution
1.6 References
Section 2 DESIGN SOLUTION
2.1 Chosen Design
Section 3. DESIGN MANAGEMENT
3.1 Requirements Traceability
3.1.1 Use Case Models to Logical/Physical Design Traceability
3.1.2 Logical/Physical Design to Configuration Item Traceability
3.1.3 User Stories
3.2 Issues and Resolutions
3.2.1 Considerations for Project Sprints
Section 4. DESIGN SOLUTION DETAIL
4.1 Application Design
4.1.1 Application Context
4.1.2 Application Prototype Description
4.1.3 Application Role Matrix
4.1.4 Application Subsystems
4.1.5 Application Interfaces
4.1.6 Parameter Settings
4.1.7 User-System Interface Structure
4.1.8 Integration Strategy
4.2 Engineered Design
4.2.1 Engineering Design
4.2.2 Cybersecurity Design
4.2.3 Privacy Design
4.2.4 User and Network Services Design
List Of Figures And Tables
Appendix A - Acronyms and Glossary

IRS Best Practices - Implementing System Development Documents

ELC Phase Goals Related Artifact/Document Initial Milestone Review Process Owner
• Project Initiation:

✓ Domain Architecture
✓ Preliminary Design
✓ Detailed Design
✓ System Development
✓ System Deployment
Describe the details of how the project will meet Section 508 requirements, the test conducted, and how risks will be controlled.
508 Accessibility and Mitigation Package:
✓ Accessibility Compliance Approach
✓ Provisions and Testing
✓ Accessibility Risks
✓ Signature Sheet
✓ 508 Project Initiation Questionnaire
✓ 508 Project Profile Form
✓ 508 Maintenance Determination Questionnaire
Initiated in MS 1 Information Resources Accessibility Program (IRAP)
Project Initiation The project sponsor authorizes and summarize the key information for the work, and appoints a project manager for the project. Project Charter

Note:

All new projects must have a Charter and be certified as IRS EA compliant.

Initiated in MS 1 Enterprise Architecture
System Development Necessary system guidance Computer Operations Handbook Initiated in MS 4B Enterprise Computing Center
System Development To identify and track the incremental hardware and software required by the project for the system environment. Government Equipment List Initiated in MS 4B Solutions Engineering Office
Project Initiation:

✓ Domain Architecture
✓ Preliminary Design
✓ Detailed Design
✓ System Development
✓ System Deployment
Adapt the requirements and specifications of a project to current operational needs of the organization. Project Tailoring Plan (PTP) or Project Management Plan Initiated in MS 1 Enterprise Life Cycle
Project Initiation To document the Configuration Management (CM) activities that an organization used to maintain Configuration items, and CI associated artifacts. Configuration Management Plan Initiated in MS 1 Service Asset and Configuration Management Office
Domain Architecture Describes the solution architecture of a program/project in business and technical terms with release plans for the deliverables. Business System Report Initiated in MS 2 Requirements Engineering Program Office (REPO)
Preliminary Design Provides the logical and physical IT system technical end-to-end design solution for the project. • Simplified Design Specification Report
 

Note:

Mandatory for all projects developing software applications

Initiated in MS 3 Solutions Engineering (SE) Office
Preliminary Design • ICD is used for two Organization system interface connections:
✓ Establishes the baseline conditions, responsibilities, and agreement of each organization for their system interface boundaries and end-to-end interface processes between the two systems.
✓ The standards, protocols and message exchange between the two systems are also established.
• Interface Control Document (ICD)

Note:

Mandator for all projects developing software applications

Initiated in MS 3 Solutions Engineering (SE) Office
Domain Architecture Document the project successes, problems, risk and /or shortfalls during the ELC to assist with future projects. Lessons Learned Report Initiated in MS 2 Investment & Portfolio Office
Project Initiation The PCLIA is created through the Privacy Impact Assessment Management System (PIAMS), and is required when collecting, receiving, storing or sharing Personally Identifiable Information (PII). • Privacy Package/Privacy and Civil Liberties Impact Assessment (PCLIA)

Note:

Formally know as Privacy Impact Assessments (PIAs)

Initiated in MS 1 Privacy and Compliance Office
Project Initiation The purpose of this Security Package is to validate that a system has the Authority to Operate (ATO) based on NIST SP 800-series. • ELC Security Package

Note:

Completed every three years. Must be completed and certified by the Process Owner before the system processes live data.

Initiated in MS 1 Security Program Management Officer https://organization.ds.irsnet.gov/sites/Cyber/CyberServices/SitePages/ELC%20Project%20Support.aspx
Domain Architecture The SDP is a standard artifact to summarized the planned deployment activities for the release. • System Deployment Plan (SDP)
✓ ELC SDP Template
Initiated in MS 2 Test Program Management & Center of Excellence
Preliminary Design • Numerous test are conducted which could include:
✓ System Integration Test (SIT)
✓ System Acceptance Test (SAT)
✓ Government Acceptance
✓ Test (GAT)
✓ Final Integration Test (FIT)
• System Test Plan (STP)
✓ ELC STP template
Initiated in MS 3 EST Test Program Management & Center of Excellence
System Deployment EoTCR provides a standard artifact to summarize the complete test efforts for the release. • End of Test Completion Report (EoTCR)

Note:

Due 30 days after project deployment

Initiated in MS 5 EST Test Program Management & Center of Excellence