GENERIC

ANALYSIS REPORT STANDARD

@(#)anastan.htm 3.5 - 02/20/05

The Generic UWF Maintenance Process (GUMP++) 1994-2000 The University of West Florida. All rights reserved.

Permission is granted to reproduce and adapt this document provided credit is given to the University of West Florida. This documentation is provided "as is" and no warranty of fitness for any particular purpose is made or implied.

ABSTRACT

This document is the Analysis Report standard for the generic maintenance process architecture for the Software Engineering graduate program at the University of West Florida (UWF). The Analysis Report (AR) is a formal document, outlining all requirements for a TISK. The AR must be approved by an inspection team and pass a Change Control Board (CCB). The Analysis Report is described in further detail in this document and in the process architecture.

TABLE OF CONTENTS

ABSTRACT
LIST OF TABLES
1.0 INTRODUCTION
2.0 ANALYSIS REPORT CONTENTS
2.1 DEFICIENCY SET DESCRIPTION
2.2 REQUIREMENT SPECIFICATIONS
2.3 DESIGN
2.3.1 Design Content
2.3.2 Documentation Change Description
2.4 TIME AND RESOURCE ESTIMATION
2.5 RISK ANALYSIS
2.6 LIST OF CODE AND DOCS
2.7 SIGNATURE BLOCK
REVISION HISTORY

LIST OF TABLES

1.0 INTRODUCTION

The AR is the first step in implementing a change to the existing software. The purpose of an AR is to describe a proposed solution to a TISK.

An AR will contain the following information: a deficiency set description, requirements specifications, an estimation of the time and the resources needed to implement the requirements, and a signature block for use in authorizing performance of the TISK. Depending on the scope of the TISK, an AR may further include a design and risk analysis of the effort involved.

2.0 ANALYSIS REPORT CONTENTS

2.1 DEFICIENCY SET DESCRIPTION

For each deficiency, the AR will list the deficiency number (e.g., DR001) and deficiency description. If a Software Engineer (SE) would like to do some code clean-up work, in addition to the set of deficiencies, the SE must include one or more requirements to describe the work that will be done.

2.2 REQUIREMENT SPECIFICATIONS

Each requirement identified in the Requirements Specifications section should be assigned a unique requirement number, such as "2.1" or "2.2", for tracking purposes. A unique requirement should be identified as one functional requirement, or characteristic, that will be developed or modified. There may be more than one requirement needed to satisfy a change requested in a single Deficiency Report(DR). If several requirements are grouped under one larger requirement heading, the individual requirements may be identified under a category heading (i.e., 2.1, 2.1.1, 2.1.2,...) for easier referencing and tracking.

Each unique requirement specification should identify these items:

• a unique requirement number,
• the associated deficiency number (e.g., DR001),
• a clear description of what the program will do,
• how the user will use the feature (where applicable),
• examples/descriptions of any output seen by the user (where applicable),
• error handling conditions/actions (where applicable),
• a sample test case that will verify that the requirement has been met.

Error handling conditions/actions for a requirement should include all error conditions that will be checked for and how the program will handle each of these conditions. Any error messages or other program reactions that will result from detection of an error being checked for should be explained and/or illustrated as necessary. As a reminder, a program should always terminate "gracefully" with meaningful user notification at the time the error first appears.

The Analysis Report team may include additional information (e.g., error handling conditions/actions) that they feel may be necessary to describe the requirements. Remember that the purpose of the AR is to communicate the proposed solution as completely as necessary.

2.3 DESIGN

The SE may use the following guidance in determining the necessary level of design. A small TISK does not require the preparation of a design. For example, a design is not needed for bug fixes or other changes that involve relatively few lines scattered through the program. For a medium TISK (>500 lines) the preparation of a design may be necessary. For a large TISK, the preparation of a design is almost essential. The PC may also suggest that an inspection of a design be performed before coding proceeds. This should be done when a large amount of new code is to be written (>2000 lines) or when there is some special reason to exercise additional control over the implementation team such as in the case for an inexperienced team if a complicated change of the software functionality is anticipated.

Design should be described to an appropriate level based on the extent of the work to be done. Major modifications will require more analysis than minor ones. It is up to the analysis team to identify the amount of design documentation necessary, and be prepared to justify their decisions in the Analysis Report inspection and to convince the CCB that they understand the scope of the change.

Each requirement identified in the Requirements Specifications section should be addressed by describing the technique that the SE intends to use to satisfy the requirement. The technique should be clearly stated so that the reviewers can understand what will be done in order to verify that the intended technique is appropriate and will work. Each requirement number assigned in the Requirements Specifications should be addressed in this section.

In describing the solutions, all code modules that will be changed should be identified by name. Any additional modules or functions that will be directly or indirectly affected by the proposed changes should also be identified, along with a brief description of the how they will be affected. The documents that need to be modified shall also be identified by file name and section number. The Documentation Engineer will be responsible for the analysis report documentation identification and a description of each document modification.

In the case of major modifications or new code modules, it may be necessary to incorporate some or all of the information outlined in the following bullets into the AR:

• Input/Output(I/O) Data Elements - This section will list all unit data elements that are either referenced or modified by this design. Data elements are listed by: name, description, data type, and I/O type (input, output, or both).


• Local Data Elements - This section will list all unit local data elements that are called for by this design. Local data elements are listed by: name, description, and data type.


• Algorithms - This section will describe all algorithms that are called for by this design.


• Error Handling - This section will identify and describe the error handling capabilities that are needed to implement the design.


• Data Conversion - This section will describe any data/format conversions that must be applied to any of the input or output data elements.


• Logic Flow - This section will describe the internal logic dictated by the design. The logic of the design can be demonstrated by using flow charts, pseudo-code, state transition diagrams, and so on. The method is up to the designer.


• Files - This section will describe any local and shared files that the design interacts with. For each file, designate whether it is local to a particular unit or shared amongst two or more units. Also describe the format and access procedures needed for each file.

2.3.2 Documentation Change Description

This section lists and describes all documentation file changes that must occur as a result of the DRs described in section 2.1 DEFICIENCY SET DESCRIPTION. Each change will be explicitly described and will contain the following:

• File Name (html file name)
• Document Name (document being modified, e.g. Recon Users Manual)
• Requirement Number
• Section and Paragraph to be modified
• Current paragraph/sentence
• Suggested paragraph/sentence

The implemented version may vary slightly from the modified version detailed here.

Time and resource estimates will be based on a combination of the lines of code and documentation that will have to be inserted or deleted to implement the various requirements. The estimate will break out the expected number of hours expected in each sub-cell of the "Implement Change" and "Independent V & V" cells. If possible, the estimates may be broken down by requirement to allow the Change Control Board to choose only some of the analyzed requirements.

It is the responsibility of the AR author to consult with IV&V for their time and resource estimates.

The following example shows the recommended estimation table breakdown by requirement (example responses in bold):

It is recommended that the Delphi Estimation Process be used to estimate the Lines of Code and Documentation to be Inserted or Deleted (LCDID). Since a number of TISKs have been completed to date using the current process, the SE may alternatively compare the actual time and resource values from the previous TISKs to the proposed LCDID. Rationale on how time estimates are derived should be provided when the Delphi Estimation Process is not used.

The risks will be broken down into an overall technical risk and an overall schedule risk. Each of these risks will be rated on a scale of 1 - 5, with 1 being very low risk and 5 being very high risk. The sum of these two numbers will give a total risk picture for the work effort.

If appropriate, a short discussion after each risk total would be helpful to the team making the decision to proceed. A few sentences to a short paragraph should be enough to describe most TISKs.

SOME TECHNICAL RISKS TO BE CONSIDERED:

• How much experience do the SEs have in the selected language?
• How complicated are the proposed changes?
• Is there a high likelihood of undesired side effects after the changes are made?
• Are development machines likely to be unavailable during the effort?
• Will e-mail communications be a problem?

SOME SCHEDULE RISKS TO BE CONSIDERED:

• Will any of the SEs be required to go TDY during the effort?
• What is the likelihood of miscommunications or misunderstandings about the requirements being a problem?
• Will holiday commitments or the end of the semester be a factor on people's schedules?

This section will provide a table cross-referencing the DR numbers with the code modules and documentation that will need to be modified or created. The following table is an example:

DR#          Module                        Documentation
-------------------------------------------------------------
15           instrment.c,instfile.c        N/A
18           instpars.c                    User Manual
35           instnew.c (created)           Readme
-------------------------------------------------------------

2.7 SIGNATURE BLOCK

The author must request another member of the SE team to perform an informal walkthrough of the proposed requirements, design techniques, and documentation before the Analysis Report is submitted for formal inspection. The SE who performs the informal walkthrough is responsible for discussing any problems noted during the walkthrough with the author. When the Analysis Report is accepted by the inspecting SE, the SE must enter his or her name and the date the report was accepted in this section of the Analysis Report before the formal inspection can be initiated.

REVISION HISTORY