Redocumentation Scenario

Overview

Symptoms

Many old systems are not well documented or documented at all. There seems to be a continuous need to understand these systems more effectively. The redocumentation scenario is aimed at providing this information for maintenance and/or redevelopment support teams.

Symptoms include:

· New or junior personnel cannot figure out what a system is doing, or supposed to be doing

· A major enhancement is held up indefinitely because analysts cannot figure out where to apply changes

· People refuse to work on a system because they cannot figure out what it does

· There is limited or nonexistent documentation showing overall functionality and user views of the system

· Functional documentation, that would allow analysts to understand what the system is doing, is cryptic, inaccurate or incomplete

· There is no technical documentation showing overall system architecture, information flows, program processing flows or system-wide data usage

Requirements

The requirements for the redocumentation scenario are identified below.

· An inventory of system components, and the interrelationship of those components, is required before undertaking a project

· System and program level data usage and process flows are required to reduce system learning curves

· Enhancement team needs high-level view of application data usage and functional breakdown to work with users in specifying change requirements

· Data administration requires data usage summary to link system data to corporate data model or as input to development of a new corporate data warehouse

· User requires summary of presentation views and supporting documentation for user training and business planning

Approach

Many organizations make the mistake of writing volumes of narrative, carefully describing exactly what a system does and how it does it. Volumes of narrative; (1) become dated as soon after they are completed and (2) are too voluminous to be read and/or assimilated. Models, metrics and machine generated reports may be assessed rapidly and updated quickly. Hopefully, this scenario will help IS organizations update documentation standards to reflect these capabilities.

One key aspect of Comsys-TIM in terms of redocumentation is the standard industry Legacy Transition Meta-model or LTM. This model, when employed in a standard repository, can be used in most of the steps defined within this scenario. This model, once populated, can serve as a configuration tracking facility, change control log, business rule cross reference facility or development/maintenance synchronization control log. Refer to the Comsys-TIM appendix for more details.

One final point is that this documentation will take time to produce. While this is true, there is no real shortcut to producing a good overview of a system's functional capabilities. Once completed, this type of documentation is easily updated using the same automated analysis and I-CASE tools that created it in the first place. This also may help organizations figure out how to put the I-CASE tools, now sitting idle, to good use.

Develop Redocumentation Plan

Create Redocumentation Plan

Note: An organization should choose various redocumentation options identified below. It is possible to create too much information and it is important to only create what is required for task at hand.

Objective setting/proposal development

Note: Form 001 may be good documentation in and of itself.

Complete Executive Planning

Note: There is no need to create/select a hypothesis since the system will not be modified during this project.

Develop Inventory Analysis Objectives

Establish Assessment Task List

Note: Refer to the actual activities in the next section to determine the scope of each task planned for below. As a rule, no metrics will be generated and manual analysis will be optional.

Finalize Environmental Analysis Work Plan

Finalize Process Flow Analysis Work Estimates

Note: "Assess multi-system data definition usage" is only performed where multiple related systems are being re-documented.

Finalize Data Definition Analysis Work Estimates

Finalize General System Architecture Work Plan

Finalize Presentation Layer Analysis Plan

Finalize Data Access Layer Assessment Plan

Note: Backlog analysis is the documentation of user requirements and may be omitted if requests are already well defined.

Finalize User Backlog Analysis Plan

Note: Next four steps focus on capturing bottom-up views of current systems as documentation.

Finalize Subject Area Analysis Work Plan

Finalize Function Hierarchy Analysis Plan

Finalize Function Dependency Analysis Plan

Finalize Function/Entity Type Analysis Plan

Note: Perform IS infrastructure analysis to determine how much training is involve in rolling some of these tools out to application area.

Finalize IS Infrastructure Analysis Plan

Note: Because most of the redocumentation work is done at this point, the interim plan involves very little effort - see actual steps that complete this scenario in remaining sections.

Finalize Interim Planning Task Effort

Develop Inventory/Analysis Work Plan

Complete Inventory/Analysis Assessment Proposal

Document Application Infrastructure

Develop Physical Documentation

Environmental analysis

Note: The following steps are performed for each system input to this assessment.

Identify/Categorize Physical System Components

Identify/Categorize External System Components

Inventory/Cross Reference Mainframe Components

Produce Environmental Counts and Scores

Process flow analysis

Note: Process flow analysis is performed for each system input to this assessment.

Verify and Finalize System/Sub-System Groupings

Perform Process Flow Analysis

Note: The following step should be performed on programs of interest, large programs, programs undergoing complex change and highly flawed programs.

Produce Detail Program Analysis Listings

Data definition analysis

Note: The following steps are performed for each system input to this assessment and gives analysts a clear understanding of cross system data usage.

Perform System-Wide Data Definition Analysis

Review Data Definition Analysis Results

Note: The following step is performed if multiple related systems are being analyzed.

Assess Multi-System Data Definition Usage

Develop Logical Flow Analysis

General system architecture assessment

Note: The following steps are performed for each system input to this assessment.

Document Batch System Information Flow

Document On-Line System Information Flow

Note: The following is performed where a system is made up of multiple sub-systems.

Develop System/Sub-System Interface Map

Note: The following step is performed if multiple related systems are being analyzed.

Document Related System Interfaces

Document Subroutine Interface Levels

Develop User Level Documentation

Presentation layer assessment

Note: The following steps are performed for each system input to this assessment.

Identify Batch Output Presentation Media

Identify/Categorize On-Line Presentation Media

Data access layer assessment

Note: The following steps are performed for each system input to this assessment.

Finalize Database & Data File Inventory

User backlog requirements analysis

Categorize User Backlog Requests

Subject Area & Entity Type Analysis

Derive Current System Subject Areas

Note: The following two steps are performed for each system being assessed.

Prepare/Load Current System Entity Types

Derive Existing Entity Relationship Diagram

Function hierarchy analysis

Note: The following steps are performed for each system input to this assessment.

Create Current Function/Process Hierarchy

Map Functions to Program Source Modules

Function dependency analysis

Note: The following step is performed for each system input to this assessment.

Derive Current System Dependency Diagram

Business Function/Entity Type Analysis

Note: The following step is performed for each system input to this assessment.

Establish Current System Matrix

Assess Support Group Capabilities

IS infrastructure analysis

Determine Staff Experience/Skill Ratings

Determine Testing Skill/Maturity Ratings

Determine IS Development Tool Ratings

Determine IS Quality/Maturity Ratings

Determine IS Summary Rating Factors

Further Employ/Rollout Documentation Facilities

Build Additional Documentation Plan

Create interim support plan

Note: Establish a plan to complete additional documentation steps as dictated by the planning steps below..

Finalize Interim Support Work Plan

Note: Verify that enough time is allocated for the third step in Data Definition Migration by reviewing it prior to finalizing the following estimating step.

Finalize Data Definition Migration Plan

Note: In following estimating step, plan to apply only the first two steps in Logical Data Analysis task.

Finalize Logical Data Analysis Work Plan

Finalize System Structure Analysis Plan

Identify Support Structure Adjustments

Integrate Interim Plan/Strategic Objectives

Create Additional System Documentation

Data definition migration

Note: The following step is performed on a system by system basis. Recommend using ReConstruction tool to load I-CASE tool.

Perform Repository Pre-Loading Analysis

Execute Repository Load Process

Note: Management procedures for the repository are finalized in the last activity of this scenario.

Logical data model abstraction

Note: Following steps produces a first cut, extracted view of primary data used across multiple existing systems.

Load/Merge Bottom-Up ER Model(s)

Refine Bottom-Up Derived ER Model

System structure analysis

Note: Perform the following step for each existing system being integrated.

Derive Current System(s) Structure Chart

Rollout Documentation Tools

Note: The following step contains multi-purpose infrastructure guidelines. Follow the guidelines applicable to the project’s circumstances.

Create Infrastructure Management Procedures