icam software documentation standards - u.s. …€¦ · icamsoftwaredocumentation standards ......

NBSIR 79-1940 (R)

FILE COPY

00 KOI REMOVE

MAR ? 2 t980

ICAM Software DocumentationStandards

Center for Programming Science and Technology

Institute for Computer Sciences and Technology

National Bureau of Standards

Washington, D.C. 20234

Final Report

February 1980

Prepared for

Air Force Materials LaboratoryWright- Patterson Air Force BaseOhio 45433

NBSIR 79-1940 (R)

ICAM SOFTWARE DOCUMENTATIONSTANDARDS

Center for Programming Science and Technology

Institute for Computer Sciences and Technology

National Bureau of Standards

Washington, D.C. 20234

Final Report

February 1 980

Prepared for

Air Force Materials Laboratory

Wright-Patterson Air Force BaseOhio 45433

U.S. DEPARTMENT OF COMMERCE, Philip M. Klutznick, Secretary

Luther H. Hodges, Jr., Deputy Secretary

Jordan J. Baruch, Assistant Secretary for Science and Technology

NATIONAL BUREAU OF STANDARDS, Ernest Ambler, Director

PREFACE

In October of 1977 the National Bureau of Standardsagreed with the Air Force Wright Aeronautical Laboratoriesto develop documentation standards for the IntegratedComputer-Aided Manufacturing (ICAM) Program. Under MIPRFY1 457-77-02054 NBS's Institute for Computer Sciences andTechnology undertook and completed this project. The docu-mentation standards included in this final repor t--NBSI

R

79-1940 (Air Force) (R)--have given NBS the opportunity toadapt and substantially extend Federal Information Process-ing Standards Publications 30, 38, and 64; moreover, theyprovide the ICAM Program with the means of ensuring high-quality software products.

-i i i -

TABLE OF CONTENTS

APPLICATION INFORMATION 1

STYLE GUIDE 11

CONTENT GUIDES 21

PROBLEM REPORT 27SOFTWARE CHANGE PROPOSAL 31

SOFTWARE CHANGE NOTICE 35DEFINITION PLAN 39FEASIBILITY STUDY 43COST/BENEFIT ANALYSIS 49REQUIREMENTS DOCUMENT 55DEVELOPMENT PLAN 63SYSTEM/SUBSYSTEM SPECIFICATION 67PROGRAM SPECIFICATION 73DATA SPECIFICATION 79STRATEGIC TEST PLAN 83DETAILED TEST PLAN 87TEST ANALYSIS REPORT 91

SOFTWARE VALIDATION REPORT 95SOFTWARE SUMMARY 99USER’S MANUAL 101OPERATIONS MANUAL 105PROGRAM MAINTENANCE MANUAL 109INSTALLATION GUIDE 113MAINTENANCE PLAN 119APPLICATION REPORT 123

I DEF MODEL 127GLOSSARY FOR IDEF MODEL 157

- v-

ICAM SOFTWARE DOCUMENTATION STANDARDS

Application Systems DivisionInstitute for Computer Sciences and Technology

The ICAM Program Office requires all contractors whodevelop ICAM software to comply with the following standardsgoverning style and content of ICAM Software Documents. TheStyle Guide, which covers writing and programming style, ap-plies to all documentation, and individual Content Guidesapply to particular software documents. All of these guidesfunction within the overall framework defined by the IDEFFunctional Model and its glossary.

Key words: Computer-aided manufacturing; computer stan-dards; programming style; software documentation; structuredanalysis.

1 . APPLICATION INFORMATION

1 . j Summary

This report provides specifications and procedures forimplementing software documentation standards in ICAM pro-jects. These standards adapt and substantially extendFederal Information .Processing Standards Publications 30,38, and 64, and DOD 7935. 1-S, for use in ICAM software con-tracts.

1 . 2 Environment

These instructions are directed to a technical staffmember of the ICAM Program Office who serves as the ContractOfficer to define requirements for ICAM software developmentand to monitor contractor performance of those requirements.The materials provided are to be implemented within any con-tract for ICAM software development.

-1 -

1.3 References

This report includes four items. First is the contractstatement of work attachment that defines the applicabilityof the standards and the pertinent contractor responsibili-ties. The others are the ICAM Software Documentation StyleGuide, the ICAM Software Documentation Content Guides, andthe IDEF Functional Model of the ICAM Software DocumentationSystem. The Contract Officer and prospective contractor arereferred as well to the FIPS PUBS 30, 38, and 6*4, and DOD7935 . 1— S. (For complete references, see the introduction tothe Content Guides, section 1.3, p. 23).

2. SCOPE

The statement of work presented below addresses onlythe documentation requirements associated with softwaredevelopment, and so is intended to supplement other contrac-tual specifications. It provides space to record ContractOfficer's decisions regarding the following: the packagingof standard documents, the contractor-proposed documents tobe delivered, and the scheduled delivery dates for documen-tation items.

The standard documents are applicable and required forany contract that includes the activity which produces them;see the IDEF Model. But different options for packaging thedocuments as separate volumes may be chosen in order tomatch document scope and size to the scope and complexity ofthe project or software product.

The statement of work is written for a contract thatcovers only one system of related computer programs. TheContract Officer must adapt the wording appropriately if twoor more distinct system developments are being undertaken inone contract.

3. IMPLEMENTATION

To incorporate the statement of work into a contract,the Contract Officer first assesses the proposed project us-ing the Table of Software Categories on page 6 to choose oneof the packaging options A, B, or C. Noting the start andend points of the project within either the software life

- 2 -

cycle or the IDEF Functional Model, he marks (S) for singlevolume documents in the selected column A, B, or C of Table1. If he chooses A, he marks (M) for those documents thatwould be acceptable as multiple volumes. He then completesthe Table by filling in the scheduled delivery dates foroutlines and full copy. Finally, he completes the Addition-al Requirements section on page 5 to include anycontractor-proposed documents that are accepted for the con-tract, any other desired documents, and any special condi-tions on preparation.

The remainder of these instructions is the statement ofwork attachment .

4. STATEMENT OF WORK FOR

SOFTWARE DOCUMENTATION REQUIREMENTS

The contractor shall prepare and deliver technical do-cuments (software documentation) as required herein, for allcomputer programs (software) that are the subject of definedtasks or original work as identified elsewhere in this con-tract. The requirements below address objectives and gen-eral requirements, required documents, their informationelements, quality and style of preparation, deliveryschedule, and other pertinent factors. The following stan-dards or guidelines are incorporated in this contract byreference and made a part of it for the purposes definedbelow: IDEF Functional Model of the ICAM Software Documenta-tion System; ICAM Style Guide for Software Documentation;ICAM Software Documentation Content Guides.

Objectives and General Requirements

Among its important objectives, the ICAM program seeksto produce and to disseminate innovative computer programsthat are readily transferred between different computer sys-tems and are useful to many manufacturing organizations.Quality software documentation is essential for accomplish-ing diverse tasks, including installing, operating, main-taining, and using computer programs, as well as transfer-ring design principles and methodologies to many parties.The contractor shall prepare software documents according tothe requirements set forth herein, and with the technicalaccuracy, completeness, and other quality attributes thatwill best meet ICAM objectives for the software involved.The stated requirements are minimum essential

- 3 -

characteristics. The contractor shall meet these fully andshall provide his best technical effort and judgment in

proceeding beyond the stated requirements to produce highlyeffective software documents.

The I DEF Functional Model for the ICAM Software Docu-mentation System shall be used by the contractor as basicguidance on document preparation, review, and acceptanceprocedures. Acceptance of software documents shall be basedupon clarity and effectiveness of presentation, accuracy,completeness for the intended purpose, and conformance torequirements .

Required Standard Documents

The required documents consist of ICAM standard docu-ments and additional contractor-proposed documents as statedunder Additional Requirements below.

Standard software documents are those defined in theICAM Software Documentation Content Guides. These are list-ed in Table 1--Standard Documents (pages 7-9), which alsoshows the activities that produce each document, as depictedin the IDEF Functional Model.

In Table 1, the three columns labeled A, B, and C pro-vide for a choice among alternative configurations or pack-aging of the standard documents as separate volumes. Onesuch column of Table 1 is marked to indicate the configura-tion that shall apply to this contract. The individual en-tries marked (S) or (M) in this column indicate the standarddocuments that must be provided because the pertinent lifecycle tasks are encompassed by this contract. Documentsmarked "S" are acceptable only as single volumes.

If column A has been marked for this contract, then a

mark (M) indicates that the pertinent document may be pro-vided as a multiple volume document, at the discretion ofthe contractor or writer, following the guidance in the ICAMContent Guides.

Wherever a box marked in column B or C includes two ormore consecutive documents, the contractor shall prepare onevolume that provides each of these included documents as a

separate part, and the parts shall be in the order shown inTable 1 (e.g., see the Feasibility Study and Cost/BenefitAnalysis in columns B and C). See the ICAM Content Guidesfor further specification.

- 4 -

Table 1 further states the required delivery schedulefor document outlines, review copy, and final copy.

Use of Style Guide

All documents pertaining to software shall be preparedaccording to the ICAM Software Documentation Style Guide,which governs narrative style, format, and other conventionsthat are independent of specific technical content.

The Style Guide also provides guidelines for computerprogramming style which shall be followed as a minimum toassure that program listings are readable source material tosupplement narrative documents.

Use of Content Guides

Each ICAM Software Documentation Content Guide beginswith a brief statement of the document's nature and purpose,and then provides an annotated outline of required contents.The information content of each standard document shall con-form, as a minimum, to the pertinent annotated outline. Thecontractor shall use each Content Guide as a basic referenceto determine the relevance and scope for information to beincluded. The contractor shall provide in each document allinformation that is essential and effective for understand-ing of the software by other parties and for fulfilling thepurpose of the document, even if such information is not ex-plicitly indicated by the pertinent Content Guide.

The Content Guide governs only the main body of thestandard document. The Style Guide specifies how the mainbody shall be incorporated into a complete document that in-cludes other essential features such as title page, table ofcontents , etc .

Additional Requirements

(The Contract Officer shall include here the appropri-ate terms and guidelines to incorporate the acceptedcontractor-proposed documents as additional contract dataitems, and also shall state the requirements for outlines,draft reports or partial drafts, revisions of previouslydelivered and accepted documents, number of copies, officialdistribution, and similar requirements.)

- 5 -

Table of Software Categories

Category DecisionFactors

C Special purpose softwarefor limited application

B

General purpose software adaptableto several applications

throughout industry

A

General purpose software especially designedfor central support of many CAM applications

throughout industry

EXAMPLES OF SOFTWARE CATEGORIES

Category C_:

COBOL program to translate a special data code (e.g.for part numbers) to a standard code devised for ICAM.

Program or subroutine to compute an engineering proper-ty (e.g. breaking limit of a given metal alloy) under spe-cial conditions .

Category B:

Programs or subroutines for use with AUTOIDEF in orderto operate a new or unusual type of computer terminal inplace of the graphics CRT.

GPSS simulation programs for existing sheet metaloperations of a particular manufacturer.

Category A

:

Library of FORTRAN programs for computing the principalengineering parameters for all standard alloys and metalforming methods used in aerospace manufacturing.

AUTOIDEF

IDSS

- 6 -

Standard

Documents

- 7 -

Specification

Standard

Documents

OJ

«D•*)

fta.

8

Software

Summary

Standarc

Documents

*’DO

QQ.

EU. V-

UJ bOQ toH -r-t

aCsJ

•X

CM

•X

vO

<

CVJ

•X

vO

<cAT

16

A1

16

Schedule

of

Deliverable

Items

Final

Copy

Complete

Review

Draft

AugmentedOutline

Document

Selection

(Use

One

Column

Only)

QQ

V

Standard

Document

Types

1

Problem

Report

Software

Change

Proposal

j

Software

Cnange

Notice

Maintenance

Plan

Acceptance

Test

Analysis

Report

j

Application

Report

Life

Cycle

StageOperation

and

i

Maintenance

j

-9 -

THIS PAGE DELIBERATELY

LEFT BLANK

ICAM

Software

Documentation

Style Guide

- 11 -


LEFT BLANK

1 . GENERAL INFORMATION

1 . 1 Summary

Used in conjunction with the content guides, the styleguide helps control the quality of ICAM Software Documents.While each content guide specifies the content of a singledocument, the style manual gives guidelines for the writingof all documents. Besides discussing good writing and pro-gramming style, it specifies acceptable format features liketypography and graphics. The writer of an ICAM documentuses the style guide with the individual content guides toprepare the main body of the document. He then incorporatesthis main body in the apparatus--t it le page, table of con-tents, glossary, e t c . --spec i f i ed by the style guide.

1 . 2 Environment

The ICAM Software Documentation Style Guide applies toall ICAM software development projects.

1.3 References

Language and Format

Air Force Wright Aeronautical Laboratories, "Preparation ofTechnical Reports," AFWALP 80-1, June 24, 1977.

Fowler, H. W . ,Modern English Usage , 2nd ed., rev. by

Gowers, Sir Ernest, Oxford U P, 1965.

Hodges, John C., and Whitten, Mary E., The Harbrac e Colleg e

Handbook, 8th ed., Harcourt Brace Jovanovich, 1977.

Leggert, Glenn H., e_t a_l. , The Prentice -Hall Handb o ok forWriters

,7th ed., Pr en t i c e -H a 1 1 , 1 978 .

Strunk, W. S., Jr., and White, E. B., The Elements o f Style ,

2nd ed . , Macmillan, 1972.

Watkins, Floyd C., and Dillingham, William B., Pra cticalEngl ish Handbook

, 5th ed., Houghton Mifflin, 1977.

Programming Style

IBM Corp., Data Processing Division, Improved ProgrammingTechnologies--An Overview, Installation Management ReportGC20-1 850-0 ,

October 1974, 1 9 P

.

Kernighan, B. W . and Plauger, P. J., The Elements o f

Programming Style, 2nd ed., McGraw-Hill Book Company, NewYork, 1 974, 1 6 8 p

.

McCracken, Daniel D., and Weinberg, Gerald M., "How to Writea Readable FORTRAN Program,” Datamation , v. 18, n. 10, Oc-tober 1972, 73-77.

Mills, Harlan, "Software Development,” IEEE Transactions onSoftware Engineering , December 1976, 265-273.

Myers, Glenford J., Software Reliability : P rinciples andPractices

,John Wiley and Sons, New York, 1976, 360p.

National Bureau of Standards, Guidelines for Documentationof Computer Programs and Automated Data Systems , Federal In-formation Processing Standards Publication 38, 15 February1976, 55p

.

Van Tassel, D., Program Style , Design, Efficienc y

,

D ebugging, and Testing , Prentice-Hall, Inc., Englewood

Cliffs, New Jersey, 1974, 256p.

Yourdon, E., Techniques o f Program Structure and Design ,

Prentice-Hall, Inc., Englewood Cliffs, New Jersey, 1975,36 4p .

2. Specification

The ICAM Style Guide consists of the Air Force WrightAeronautical Laboratories Pamphlet entitled "Preparation ofTechnical Reports” (AFWALP 80-1), together with the changesand additions that follow. The first part gives furtherguidelines for standard English usage, the second specifieschanges in AFWALP 80-1, and the third adds recommendationsfor programming style specifically addressed to the ICAMcommunity, which will use FORTRAN 77.

3. Compliance with the Style Guide

Both AFWALP 80-1 and its ICAM additions repeatedly usethe imperative mood to instruct writers of technical re-ports. For example, the first sentence of Chapter 1 states,"Do not overestimate the reader's knowledge of the subjectmatter of the report." Such statements shall have the forceof contractual requirements.

4. ADDENDUM TO AFWALP 80-1

4.1 English Usage

Add the following material to Chapter 1 under thedesignated sections:

1-1 Choose an appropriate organizing principle for thedocument--e

. g . , logical development, chronological se-quence, or progression from general concepts to specif-ic instances or examples.

1-2 Every paragraph shall have a single thesis supportedboth by concrete examples from the software field andby specific and general reasoning. Paragraphs shall be

clear, unified, and logically consistent. In addition,the writer shall make clear, logical transitionsbetween paragraphs and develop each paragraph coherent-ly from one statement to the next.

1-3 Add these sections:g. Use active voice to make clear who or what is perform-

ing each action. Such information is important, oftencrucial, to the reader's understanding.

h. Use parallel structure to organize words, phrases, andclauses into understandable sentence units. For exam-ple, in the phrase "not only . . . but also . . ." thewords between "only" and "but" should be syntacticallyequivalent to the words following "also." If the firstgroup of words forms a clause, the second should alsobe a clause (with subject and verb) and not just a wordor phrase .

i. Use works like Fowler's Modern English Usage and a

standard dictionary to ensure good usage and properdiction. For further suggestions about style, consultThe Elements o f Style , by William S. Strunk and E. B.

White .

j. Use correct punctuation to help the reader understandthe logic of each statement. Make use of the differ-ences between commas, dashes, parentheses, colons, andsemicolons. For further reference consult any of thefollowing handbooks: Practical English Handbook , 5thed . , ed. Watkins and Dillingham; The Harbrace CollegeHandbook

, 8 th ed . , ed. Hodges and Whitten; or ThePrentice -Hall Handbook for Writers , 7th e d^ . , e d . GlennL e g g e r t e_t a 1_

.

k. When possible, substitute verbal forms (infinitives,participles, gerunds) for n oun s--e spe c i a 1 1 y long nounswith repetitious suffixes like "tion," "ness," and"ment." Verbal forms read more easily and help thewriter avoid long strings of abstract nouns--like "com-puter program configuration item identification docu-mentation." An infinitive is the "to" form of a verb,as in "to walk"; a gerund is the " -ing" form of a verb,used as a noun, as in "seeing"; a participle is eitherthe present or the past participle of a verb (for regu-lar verbs the "-ing" or "-ed" forms), used as an adjec-tive. In the following sentence "to understand" is aninfinitive, "Documenting" is a gerund, and "confused"is a participle: Documenting computer programs enablesnew or confused programmers to understand the intent ofthe code .

4.2 Changes to AFWALP 80-1

Make the following changes in the existing text ofAFWALP 80-1

.

2~5

.

Table of Contents Because the Table of Contents listspage numbers for sections of the document, the last sentenceof this section--" (Page numbers . . . numerals.)"— is ambi-guous. Substitute this sentence: "(Number the Table of Con-tents itself with lower-case Roman numerals, beginning withpage 'v.')"

2-6. List of Illustrations Substitute this sentence for thefirst sentence: "If the document has illustrations, providea list of illustrations giving figure number, title, andpage number for each illustration."

2-7 List of Tables Substitute this sentence for the firstsentence: "If the document has tables, provide a list oftables giving table number, caption, and page number foreach table."

- 16 -

Chapter 3: Body of Report Delete the text of this entirechapter. Substitute the content guide for the particulardocument being prepared.

4-1 . Report Text Replace all of this section with the fol-lowing paragraph: "Number and label sections as specified bythe individual content guides. Center first-level headings(like "1. GENERAL INFORMATION"); then triple space and in-dent the first line of text. Second-level headings shall be1 e f t- ju s t i f i ed . Then double space and indent the first lineof text. In all documents third-level and fourth-level sub-divisions are optional. When used, third-level headingsshall be left- just if ied , numbered with appropriate three-digit numbers (like "2.2.3"), and underlined. The textshall follow on the same line. When fourth-level headingsseem appropriate, number and indent but do not underlinethem. The text shall follow on the same line, and subse-quent lines shall be indented the same as the heading. (Foran example of text formats, see the replacement for Attach-ment 14 that follows the recommendations for programmingstyle. Its title is "Example of Numbered Paragraph Headingsand Subhead ings .

)

4-6. Computer Runs For the first sentence substitute thefollowing sentence: "Submit a printer original of computerruns."

4.3 Programming Style

The following material constitutes Chapter 10 of AFWALP80-1 .

10. Programming Style

The recommendations that follow focus on features ofprogramming style that make programs in higher levellanguages easier to read. To some extent they imply a

methodology that includes such principles as structured pro-gramming; however, they do not constitute a methodology. Donot consider these recommendations as a substitute for a

complete methodology of programming practices. Instead,view them as an assortment of principles that will enableother programmers and analysts to understand programs betterand maintain them more easily. In general, remember thatsoftware costs now greatly exceed hardware costs, so thatprogram code should cater to human readers rather than tomachines. Programming practices that obscure the purposeand function of the code are usually not worth whatever in-crease in performance they may achieve. The categories that

- 17 -

follow group related requirements for better programmingstyle .

10.1. Commentary

Every program module shall begin with a narrative that

explains the purpose and method of the module. Add furthernarrative comments within the module to explain a particularstatement or group of statements. Comments shall not merelyrepeat formulas from the code, but they must agree with theactual function of the code. Avoid excessive comments thatobscure rather than clarify the function of the program or

statement. Use complete, concise sentences to clarify the

code. It should be easier to understand the function of a

block of code by reading the comments than by reading the

code itself

.

10.2 Redundancy

To avoid unnecessary redundancy, use library functionsand write subroutines or function calls instead of repeatingcode. Do not make the reader of a program interpret thesame expression or function more than once.

10.3 Naming Conventions

Use mnemonic names and .labels like "YMAX" or "BSQR" tohelp the reader remember the identity and purpose of vari-ables, statements, functions, and subroutines. Number la-beled statements in ascending order so that their relativepositions are immediately clear. Declare all data, even ifdefault types are correct. Do not prefix a mnemonic namewith a default type letter. For example, use "COUNT" ratherthan "ICOUNT" for an integer variable, and "JOULES" ratherthan "RJOULES" for a real variable.

10. A Structured Code

Limit all program modules to about fifty (50) lines ofexecutable code. Each module shall have a single function,and couplings between modules shall be clear. Insofar aspossible, modules shall be independent so that maintenancewill be easier. If a mathematical expression requires a

continuation line, break the expression into more than onepart, using mnemonic variables for intermediate results.

Use single entry, single exit structures whenever pos-sible. For example, the Block IF Statement of FORTRAN 77simulates a structured "IF . . . THEN . . . ELSE," and thenew expressive powers of the FORTRAN 77 DO loop can simulatea structured "While . . . DO." Give each DO statement itsown CONTINUE statement. Minimize the use of COMMON blocks.

Avoid FORMAT statements; in FORTRAN 77, READ, WRITE,and PRINT statements can incorporate formatting informationand thus make a labeled FORMAT statement unnecessary.

10.5 Miscellaneous

Indent code to show nesting levels.

Write straightforward rather than clever code.

- 19 -

EXAMPLE OF

NUMBERED PARAGRAPH HEADINGS AND SUBHEADINGS

2. REQUIREMENTS

This page is an example of properly numbered and for-matted headings and subheadings. Only two levels of headingare required; when third and fourth levels seem appropriate,they should follow the format shown and explained below.For first level headings, the text is indented on the firstline but not on subsequent lines.

2.1 Per formance

The text for second-level headings is indented on thefirst line but not on subsequent lines.

2.1.1 Timing The text for third-level headings begins onthe same line and is not indented on subsequent lines.

2.

1.1.1

Response Time. The text for fourth-levelheadings begins on the same line and is indented thesame as the heading.

Attachment 1

4

- 20 -

ICAM

Software

Documentation

Content Guides

-21 -


LEFT BLANK


1 .

1

Summary

The following introduction to the ICAM Software Docu-mentation Content Guides explains how to use them. The pur-pose of the guides is to specify the organization and con-tent of the information that contractors shall provide in

particular ICAM Software Documents.

1 .

2

Environment

The ICAM Software Documentation Content Guides apply toall ICAM software development projects, and are establishedas contractual requirements for Air Force sponsored pro-jects. The contractor shall treat the preparation of docu-ments as a continuing effort that covers preliminary drafts,changes and reviews, and the final documents in theirdeliverable forms.

1.3

References

Department of Defense, Automated Data Systems DocumentationStandards , Standard 7935. 1 -S , 13 September 1977, 124p.

ICAM Program Office, ICAM Software Documentation StyleGuide , 30 April 1 979 .

National Bureau of Standards, Guidelines for Documentationo f Computer Programs and Automated Data Systems , Federal In-formation Processing Standards Publication 38, 15 February1976, 55p

.

National Bureau of Standards, Guidelines for Documentationof Computer Programs and Automated Data Systems For theInitiation Phase , Federal Information Processing StandardsPublication 64, 1 August 1979, 54p.

National Bureau of Standards, Software Summary forDescribing Computer Programs and Automated Data Systems

,

Federal Information Processing Standards Publication 30, 30June 1974, 4p.

- 23 -

DOCUMENT AUDIENCES2 .

Each Content Guide specifies a particular audience thatthe document shall address. This audience may be a personor a group of persons who will use the document to perform a

f unct ion--e . g . , design, programming, operation, maintenance.In presenting the information specified by the ContentGuide, the writer of the document shall use terminology anda level of detail appropriate to this audience.

3. REDUNDANCY

he Content Guides for ICAM Software Documents areredundant in two ways. Each of them includes introductorymaterial to give the reader a frame of reference independentof other documents. Secondly, several documents may providethe same information but differ in context, terminology, andlevel of detail in order to address different audiences atdifferent points in the software life cycle.

4. FLEXIBILITY

The following paragraphs explain how document writersor contractors can use the flexible features of the ICAMSoftware Documentation Standards.

4.1 Length of Documents

Each Content Guide applies to documents ranging from afew to several hundred pages. The length depends on thesize and complexity of the project and the judgment of thewriter as to the level of detail necessary for the environ-ment in which the software will be developed or run.

4.2 Combining Document Types

If the contract statement of work specifies one or morecombined volumes, the contractor shall provide all the in-formation required by the Content Guides for the individualdocuments being combined in a given volume. The contractorshall use the appropriate Content Guides as directions for

- 24 -

preparing specific parts of the combined document. For, ex-ample, he may prepare one volume containing in three indivi-dual parts the information specified by the Content Guidesfor the Feasibility Study, the Cost/Benefit Analysis, andthe Requirements Document, respectively. The parts shallappear in the volume in the same order as the pertinent Con-tent Guides appear herein.

4.3 Expanding Document Types

Whenever a particular document has too much informationto fit conveniently into a single volume, the contractor canpropose to divide it into appropriate units. Depending onthe nature of the system, the contractor may prepare a

separate document for each module or subsystem , or he maydivide the contents between sections. For example, the Re-quirements Document could become three volumes, one forFunctional Requirements, one for Data Requirements, and a

third for Performance and Other Requirements. Acceptance ofcontractor proposals of this type will be indicated by per-tinent Additional Requirements in the contract statement ofwork for software documentation.

4 . 4 Format

The Content Guides have been prepared using a generallyconsistent format. Each guide begins with a brief statementof the document's nature and purpose, and then provides anannotated outline that governs the main body of the standarddocument. The Style Guide specifies how the writer shallincorporate the main body into a complete document that in-cludes other essential features such as title page, table ofcontents , etc

.

4.5 Sequence of Contents

Each Content Guide specifies a broad outline forpresenting required information. The writer shall followexactly the numbered topics and use the designated topicheadings. Where the Content Guide does not specifystructure--e.g.

, within second-level headings--the writershall decide how best to subdivide and organize the requiredinformat ion

.

- 25 -

4.6 Flowcharts, Tables, and Forms

Since graphical representations often clarify narra-tive, the writer shall supplement the information specifiedin the Content Guide by any graphs, charts, or tables thathe deems necessary or desirable.

- 26 -

PROBLEM REPORT

The Problem Report formally documentssoftware problems and alerts appropriatepersonnel. These problems may range fromserious (not routine) bugs to softwarefailures or major problems with the softwareor the software development project. Thedeveloper prepares the report for his ownuse as well as for the ICAM Program Office.A user may prepare it and send it to theICAM Program Office or maintenance contrac-tor. In either case the audience may be as-sumed to be both legally and technicallycompetent to judge the importance of theproblem. Problem Reports may be issued, atany time in the software life cycle afterthe definition phase.

- 27 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the nature of the problem, telling where andwhen it occurs and suggesting possible sources of the prob-lem.)

1 . 2 Environment

(Identify the developer or user reporting the problem,and tell when and where the problem was first detected.Describe the software system and its operating environment,including software interfaces as well as the hardware onwhich the software runs.)

1.3 References

(List applicable references, such as:

* Related Problem Reports;* Affected project documentation;* Related Software Change Documents;* Documents from related projects;* Relevant standards or guidelines, including FIPS

publications, DIDs, and DoD manuals.)

2. DETAILS

2 . 1 Background

(Trace the history of the problem from its initialdetection to the present. Give the dates and contents ofProblem Reports or Software Change Documents that addressclosely related problems.)

- 28 -

2.2 Circumstances

(Describe in detail the circumstances under which theproblem occurred. If the affected software is not yetoperational, explain what factors are in conf 1 ict--e

.g .

,

contradictory requirements or specifications. If thesoftware is being tested or operated, tell which inputs pro-duce the problem. In either case, state explicitly what theproblem is and, if possible, why it occurs.)

2.3 Recommendations

(Judge the seriousness of the problem and recommendpossible actions to deal with it.)

- 29 -


LEFT BLANK

- 30 -

SOFTWARE CHANGE PROPOSAL

The Software Change Proposal recommendschanges to the requirements, specifications,documentation, or actual operating charac-teristics of the software system. In any ofthese cases the Software Change Proposalshall completely specify both the old andthe new versions of the software, includingnecessary changes to software documentation.In addressing it to the contractor's ownproject supervisor as well as to the projectmanager from the ICAM Program Office, thewriter may assume that his audience is bothlegally and technically competent to judgethe importance of the software change. Ei-ther the contractor or the ICAM Program Of-fice can produce the Software Change Propo-sal during any phase of the software lifecycle, but both parties must agree to thechange before the document becomes legallybinding .

- 31 -

ANNOTATED OUTLINE


1 . 1 Summary

(State the purpose of the Software ChangePr oposa l--i . e . ,

whether the changes affect the requirements,specifications, documentation, or operation and maintenanceof ICAM software.)

1 . 2 Environment

(Name the developer, the potential manufacturing func-tions, the hardware and software interfaces, and the possi-ble operating sites of the software system.)

1 . 3 References


* Related Problem Reports;* Affected project documentation;* Related Software Change Proposals or Notices;* Documents from related projects; and* Relevant standards or guidelines, including FIPS


2. DESCRIPTION

2.1 Function

(Describe the purpose of the software that is affectedby the proposed change.)

- 32 -

2.2

Old Version

(Indicate the software version which will be replacedif the proposed change becomes effective.)2.3

New Version

(Indicate the software version which would go into ef-fect with the proposed change.)

3. JUSTIFICATION

3.1 Background

(Trace the history of the situation which this particu-lar Software Change Proposal addresses. Recount the eventswhich make the change advisable, giving dates and contentsof previous Problem Reports or Software Change Proposals orNotices that addressed the same or a closely related issue.)

3 . 2 Alternatives

(Describe alternative changes in the software whichcould also solve the stated problem or achieve the desiredimprovement . )

3.3

Costs and Benefits

(Assess the costs and benefits (to both the contractorand the ICAM Program Office) of the recommended change

.

Justify these costs and benefits relative to those of keep-ing the software as it is or making one of the alternatechanges. State explicitly the reasons for preferring thischange to other possible actions.)

3.4

Impact

(Describe the impact of this change on the softwareproject. Name other documents which the change will affect,and tell how to update or revise these documents. Estimatethe effect of the change on the project schedule. If thechange may make it difficult for the developer to meet

- 33 -

contractual obligations, spell out anticipated problemssuggested solutions.)

- 34 -

a nd

SOFTWARE CHANGE NOTICE

The Software Change Notice authorizesproposed changes to the requirements,specifications, documentation, or actualoperating characteristics of the softwaresystem. In any of these cases the SoftwareChange Notice shall completely specify boththe old and the new versions of thesoftware, including necessary changes tosoftware documentation. In addressing it tothe contractor's own project supervisor aswell as to the project manager from the ICAMProgram Office, the writer may assume thathis audience is both legally and technicallycompetent to judge the importance of thesoftware change. Acting together, the con-tractor and the ICAM Program Office can pro-duce the Software Change Notice during anyphase of the software life cycle.

- 35 -

ANNOTATED OUTLINE


1 . 1 Summary

(State the purpose of the Software Change N o t i c e -- i . e .

,

whether it authorizes changes to the requirements, specifi-cations, documentation, or operation and maintenance of ICAMsoftware.)

1.2 Environment

(Name the developer, the potential manufacturing func-tions, the hardware and software interfaces, and the possi-ble operating sites of the software system.)

1 . 3 References


* Related Problem Reports;* Affected project documentation;* Related Software Change Proposals or Notices;* Documents from related projects; and* Relevant standards or guidelines, including FIPS


2. DESCRIPTION

2.1 Function

(Describe the purpose of the software that the author-ized change will affect.)

- 36 -

2.2 Old Version

(Indicate the software version which will be replacedwhen the change becomes effective. Summarize the formercharacteristics, functions, etc. that are changed, replaced,or deleted.)

2.3 New Version

(Indicate the software version which will go into ef-fect with the change. Summarize the new characteristics,functions, etc., and reference or attach complete documenta-tion changes effecting the change.)

3. EFFECTIVE DATE

(Give the date the Software Change Notice goes into ef-fect. )

- 37 -


LEFT BLANK

- 38 -

DEFINITION PLAN

The Definition Plan is the first tech-nical document in the development of a newsoftware system. The Plan specifies the ob-jectives, tasks, method, and schedule foranalyzing application needs and defining re-quirements of the proposed software. Thisdocument is prepared for the ICAM ProgramOffice and other participants in theanalysis and definition effort.

- 39 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the purposes envisioned for the software.)

1 . 2 Environment

(Identify the analysis and definition project partici-pants. For the software, describe potential manufacturingusers, hardware and software environments, and possibleoperating sites . )

1.3 References

(List applicable references:

* Problem background;* User requirements;* Other relevant information in published documents.)

2. BACKGROUND

2.1 Problem

(State the nature of the problem or the manufacturingapplication that requires a software solution.)

2.2 Scope

(Define the scope of the project -- that is, establishthe boundaries for what the software should and should notdo . )

- 40 -

2 . 3 Objectives

(Specify the purpose, goals, and key features of thesystem to be defined. Describe envisioned interfaces to ex-tant systems. Identify future plans. Present the objectivesin terms of relevant manufacturing applications. )

3. PLAN

3.1 Tasks

(Describe the tasks that must be performed to initiatethe development process. Specifically include feasibilityanalysis, cost/benefit analysis, and definition of function-al, data, and performance requirements. For each task,specify goals, assumptions, constraints, and expected scopeof results . )

3 . 2 Schedule

(Develop a schedule and associated milestones for thetasks defined. Include appropriate charts and other graphicdisplays, such as PERT charts.)

3.3 Approach

(Describe the strategy to be used in the analysis pro-cess, and identify software tools and methodology that mustbe used during the Analysis and Definition stages, such asIDEF versions 0, 1, and 2.)

3.^ Resources Required

(Estimate manpower and resources required to performthe individual analysis tasks. Identify project partici-pants’ contributions by task.)


LEFT BLANK

- 42 -

FEASIBILITY STUDY

This document presents concepts, broadrequirements, and objectives of the proposedsoftware system. The Feasibility Studyevaluates pertinent software solutions andtechnology relative to application goals andneeds; it compares these alternativesoftware approaches and recommends onesoftware design approach as best for the en-visioned application. Intended formanagers, this document should provide themwith adequate information to make a decisionwith respect to the further development ofthe proposed system. This study should beprepared during the initial stage ofsoftware development.

- 43 -

ANNOTATED OUTLINE


1 . 1 Summary

(Identify systems analyzed and briefly state major con-clusions . )

1 . 2 Environment

(Identify the analysis team, potential manufacturingusers, hardware and software environment, including inter-faces, potential interaction with other systems or organiza-tions, and possible operating sites for the software sys-tem.)

1 . 3 References

(List applicable references, such as the DefinitionPlan. )

2. MANAGEMENT SUMMARY

(Summarize pertinent facts about the recommended sys-tem. State the recommendations, justification, envisionedschedule of development, and end products. Include relevantinformation from the Cost/Benefit Analysis. Brieflydescribe requirements -- e.g., new services and increasedcomputing capacity. List the goals and objectives of therecommended system -- e.g., to automate control functions insheet metal fabrication. Identify assumptions and con-straints affecting the recommended system, such as opera-tional life of the proposed system, available resources, andchanging hardware or software environment. Summarize themethods used in performing the feasibility analysis -- e.g.,survey, modelling, and simulation. Identify evaluation cri-teria used in arriving at recommendations.)

3. SYSTEM REQUIREMENTS AND OBJECTIVES

3.1

Requirements

(Describe the proposed system's broad requirements, andidentify mandatory items. Include i n pu t / ou t pu t , filesdescriptions, validation criteria, major processing or dataflow, security, privacy, and control, and any required in-terfaces with other systems.)

3 .

2

Objectives

(Identify and explain in detail the major objectives ofthe proposed system -- for example, to reduce manpower andequipment cost, increase processing speed, improve efficien-cy of manufacturing process, and increase productivity.)

4 . ANALYSIS OF EXISTING SYSTEM

(Information on the existing system provides a basisfor comparison and for determining economic and managementadvantages of the proposed system. The Functional, Informa-tion, and User models prescribed by the IDEF methodology canbe attached to this portion of the study. If the IDEFmethodology is not used, details in this section provideguidance on information elements to be included in theanalysis of an existing system.)

4.1 Processing/Data Flow

(Describe in detail the processing, data flow, andfunctions performed by the current system. This descriptionmay use graphical representations.)

4.2

Workload

(Specify the volume of work handled by the existingsystem .

)

- 45 -

4.3

Costs

(Itemize, in terms of such factors as manpower andequipment, the costs incurred in operating the existing sys-tem.)

4 .

4

Personnel

(Identify skill categories and personnel required tooperate and maintain the current system.)

4.5

Equi pment

(Describe the equipment used by the existing softwaresystem . )

4 .

6

Limitations

(Identify and describe the limitations of the existingsystem, such as inadequate response time, or inability tomeet new requirements.)

4.7

Special Considerations

(Identify other factors unique to this system.)

5. PROPOSED SYSTEM

5.1 Description of Proposed System

(Present the overall system concept, and describe howit satisfies the requirements defined in section 3.)

5.2 Improvements

(Describe in detail how the proposed system will meetthe objectives in section 3.2)

- 46 -

5 . 3 Impact

(Describe the anticipated effect of the proposed systemon the current operating environment -- equipment impact,software impact, organizational impact, and operational im-pact. Also include a discussion of potential conversionproblems .

)

6.

ALTERNATIVE SYSTEMS

(Using the outline of section 5, describe each alterna-tive software approach considered. In each case, state thereason for not choosing this approach. If no alternativeswere considered, so state.)

6.1 Alternative System 1

6.2 Alternative system n

7.

RATIONALE FOR RECOMMENDATION

(Justify selecting the proposed system over the alter-native software solutions. Include required resources, pos-sible effects of delay, consequences of not taking action,and all quantifiable and non-quant i fiable benefits.)

8.

PROPOSED SCHEDULE

(Outline a proposed schedule to include design, con-struction, testing, conversion, and implementation. Identi-fy major milestones and management decision points.)

- 47 -


LEFT BLANK

- 48 -

COST/BENEFIT ANALYSIS

This document provides managers, users,designers, and auditors with estimates ofcosts and benefits for the alternative ap-proaches considered. It considers recurringand non-recurring costs, as well as tangibleand intangible benefits. This document is

prepared during the initial phase ofsoftware development, concurrently with theFeasibility Study.

--4 9 -

ANNOTATED OUTLINE


1 . 1 Summary

(Identify systems studied and briefly state major con-clusions . )

1 . 2 Environment

(Identify the analysis team, the potential manufactur-ing functions, the hardware and software interfaces, and thepossible operating sites of the software system.)

1.3 References


* Definition Plan

;

* Feasibility Study;* Other relevant project documentation.)

2. MANAGEMENT SUMMARY

(Present a concise overview of the cost/benefitanalysis conducted. Summarize recommendations for develop-ment and operation of the system. State the purpose and thescope of the cost/benefit analysis, the alternatives fordevelopment and operation, and major cost elements. Brieflydescribe the operational requirements, system life, andworkload for which the cost/benefit analysis was conducted.Identify the assumptions and constraints affecting thecost/benefit analysis. Summarize the procedures for con-ducting the cost/benefit analysis, and the techniques forestimating and computing costs. These techniques may be de-tailed in an appendix. State criteria for evaluating alter-native systems -- for example, organizational objectives,efficient operation, etc.)

- 50 -

3. DESCRIPTION OF ALTERNATIVES

(This section should be organized to provide a meaning-ful and logical presentation of alternatives.)3.1

Current System

(Describe the technical and operational characteristicsof the current system.)

3.2

Proposed System

(Describe the technical and operational characteristicsof the proposed system.)

3.3

Alternative System 1

(Describe the technical and operational characteristicsof alternative system 1.)

3.4

Alternative System n

(Describe the technical and operational characteristicsof alternative systm n.)

4. COSTS

(Describe the costs of developing and operating eachalternative system. If there is an existing system, includecosts associated with its continuation. Where applicable,compare in-house costs with contractor costs for developing,operating, or maintaining a system.)

4.1 Non-Recurring Costs

(Present non-recurring costs of each alternative overthe system's life. Include such categories of costs as:

* Capital investment cost, including the cost of ac-quiring, developing, and installing ADP equipment,and the cost of setting up a data processing facili-ty.

-51 -

* Other non-recurring costs, such as requirements and

design studies, database preparation, ADP softwareconversion, and procurement planning and benchmark-ing.)

4.2

Recurring Costs

(Present periodic costs for operating and maintainingeach alternative over the system's life -- for example,equipment, data communication, software lease and rental,personnel salaries and fringe benefits, direct support ser-vices, and travel and training.)

5. BENEFITS

(Describe non-recurring and recurring benefits whichcould be attained through the development of each proposedalternative. State benefits in quantifiable or non-quantifiable terms that relate to organizational objectives,goals, missions, functions, and operating environment.)

5.1 Non-Recurring Benefits

(Describe quantifiable benefits such as co.st reduction,value enhancement to application systems, and others.)

5.2

Recurring Benefits

(Present periodic benefits resulting from operating andmaintaining the alternative over the system's life. Includesavings realized from equipment lease, data communicationlease, personnel salaries and fringe benefits, and costavoidance resulting from choosing the "best" alternative.)

5.3

Non-Quantif iable Benefits

(Describe benefits that cannot be quantified, such asimproved service and reduced risk of incorrect processing.For those intangible benefits that can be assigned values interms of estimates and tradeoffs, include boundary estimatesand tradeoffs with tangible benefits.)

- 52 -

6 . COMPARATIVE COST/BENEFIT SUMMARY

(Present the information below in a manner that facili-tates comparison. Provide supporting documentation, as re-quired, for validation and management review.)6.1

Cost of Each Alternative Over the System Life

(For each alternative, present costs in the period inwhich they will be incurred. Include non-recurring costs,recurring costs, total costs, system life costs, presentvalue costs, residual costs, and adjusted costs.)

6.2

Benefits

(Identify the period of benefits. Enter the quantifi-able benefits for the period in which they accrue, and makepr esent-value calculations.)

6.3

Net Present Value

(Calculate the net present value by subtracting the ad-justed cost from the total present value of benefits.)

6.4 Benefit/Cost Ratio

(Calculate the benefit/cost ratio by dividing the totalpresent value by the adjusted cost.)

6.5 Payback Period

(Determine when the sum of benefits first exceeds thetotal cost.)

7. SENSITIVITY ANALYSIS

(Sensitivity Analysis assesses the sensitivity of costsand benefits to changes in key factors. Sensitivity analysesconducted on different configurations with each alternativeproposal provide a range of costs and benefits which islikely to be better than a single estimate.)

- 53 -

7 . 1 Methodology

(Describe the approach, assumptions, and model for thesensitivity analysis. Describe the analysis of sensitivityfactors. For example, consider the effects of varying suchfactors as length of system life, volume, mix, or pattern ofworkload, requirements, and configuration of equipment orsoftware; also consider the effects of alternative assump-tions on such factors as inflation rate, residual value ofequi pment

, etc .

)

7.2 Sources of Data

(Identify the sources of data for the sensitivityanalysis; also identify the method used for data collectionand the quality of data.)

7.3 Other Factors

(Identify other factors which may affect the assessmentof cost benefits, either quantitatively or qualitatively,for one or more alternatives, but are not amenable to sensi-tivity analysis or its implications.)

7.4

Results

(Identify and display in convenient fashion the resultsof the sensitivity analysis for all alternatives and fac-tors. )

7.5

Evaluation and Conclusion

(Present the key points of the sensitivity analysis,evaluate its validity and implications, and present the con-clusion. )

- 54 -

REQUIREMENTS DOCUMENT

The Requirements Document defines thefunction, data, performance and other de-tailed requirements of the proposed softwaresystem. This document is used to assurethat software designers and prospectiveusers are thoroughly and equally well in-formed of the intended capabilities andoperation of the envisioned software. It isprepared during the System Definition stage,and substantially extends and refines thebroad outline for the recommended softwarepresented in the Feasibility Study.

- 55 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the general nature of the software to bedeveloped . )

1 . 2 Environment

(Identify the system developer, the analysis team, thepotential manufacturing users, the hardware and software en-vironment, and the possible operating sites of the softwaresystem.

)

1 . 3 References


* Def inition Plan

;

* Feasibility Study;* Cost/Benefit Analysis;* Other related project documentation.)

2. OVERVIEW

2 . 1 Background

(Briefly describe the problem the software will solve,state the scope of the software, and provide any informationthat is relevant to the derivation of requirements for thissoftware system .

)

- 56 -

2 . 2 Objectives

(Specify the purpose, goal, and key features of thesystem to be developed. Describe the objectives in terms ofmanufacturing applications.)

2.3 Existing Methods and Procedures

(Describe how the present methods, procedures, or sys-tem fulfill current needs. Include information such as func-tions performed by the present system, methods and pro-cedures used, volume and frequency of data, and deficienciesand limitations of the current system.)

2.4

Proposed Methods and Procedures

(Describe the proposed software and its capabilities.Identify techniques and procedures to be used in the newsystem. Identify the requirements that the proposed softwarewill satisfy. If special software tools or methodologies areused in generating the requirements, describe them, and at-tach the results . )

2.5

Summary of Improvements

(Itemize improvements to be obtained from proposedsoftware, such as acquiring new capabilities, upgrading ex-isting capabilities, eliminating deficiencies, etc.)

2.6

Summary of Impacts

(Summarize anticipated impacts of the proposed softwareon the present system. Include a description of requiredchanges to the current hardware configuration or to existingsoftware; also describe the potential impact on the organi-zational structure, operational procedures, and developmen-tal activities . )

2.7

Cost Considerations

(Describe resource and cost factors that may influencethe development, design, and continued operation of the pro-posed software .

)

3. FUNCTIONAL REQUIREMENTS

3.1 Functions

(Describe in detail the functionsthe proposed system, and indicate howsatisfy the stated objectives.)

that are required ofthese functions will

3.2 Processing

(Describe processing requirements,facilities, telecommunications, etc.)

such as hardware ,

3.3 Support

data(Identify support requirements, such as software tools,communication software, test software, etc.)

3.4 Interf ace

(Identify required interfaces with other systems ,with

components within the same system. Also describe user in-terfaces, where appropriate.)

4. DATA REQUIREMENTS

4.1 Data Description

(Describe the data required for the software system. Ifdata already exists, identify the database (or the file)names, and describe the required changes, if any. Describethe characteristics of the data, such as acceptablerepresentation, formats, relationships, 1 o g i c a 1 / phy s i c a 1

groupings, value ranges, critical values, and others.)

- 58 -

4 .

2

Input /Output

(Describe the required inputs and outputs for the pro-posed software. Include information about source, location,and input/output media. Tie the I/O back to particularfunctions or groups of functions.)4.3

Frequency and Volume

(Indicate the expected volume of the required data, andfrequency of collection and access.)

4.4

Activity

(Describe the projected data activity; include informa-tion about data access, manipulation, and update.)

4 .

5

Constraints

(State the constraints on the data requirements, suchas limits for further expansion or utilization, maximumsize, control requirements, security, and integrity of thedat a . )

4.6

Collection

(Describe methods of collecting data, sources of thedata, storage media, data validation criteria, and data col-lection responsibil ties . Provide specific instructions fordata collection procedures.)

5. PERFORMANCE AND OTHER REQUIREMENTS

5.1 Per f ormance

(State performance requirements for the system, includ-ing system availability, responsiveness, data access ability,and response time. If applicable, describe the use of per-formance monitors, benchmarking, or modelling tools forderiving performance requirements, and attach results. Tieperformance criteria back to particular functions or groupsof functions.)

- 59 -

5.2

Security

(State the security requirements for the system.Describe special procedures to be used in ensuring securi-ty.)5.3

Integrity and Reliability

(State the system integrity and reliability require-ments . )

5.4

Flexibility

(Describe the requirements for adaptability of the pro-posed system to changes in mode of operation, in interfacingwith other software, and in adapting to integration intodifferent operating environments.)

5.5

Failure Contingencies

(Specify possible failures of the software or thehardware, and the consequences (in terms of performance),and describe alternative courses of action that can be takento satisfy the informational requirements. Include suchtechniques as back-up, fallback, and recovery and restart.)

6. OPERATING ENVIRONMENT

6.1 Equipment

(Identify the equipment required to operate thesoftware, including new equipment, and relate it to specificfunctions and requirements. Include information about theprocessor, the size of the internal storage, online and off-line auxiliary storage media, forms, and devices, and otherinformation . )

- 60 -

6.2 Controls

(Describe the operational controls imposed onsoftware. Identify the source of these controls.)

the

- 61 -


LEFT BLANK

- 62 -

DEVELOPMENT PLAN

The Development Plan describes the or-ganization, resources, tasks, schedule,methods, and standards for development ofsoftware, beginning after the requirementsdefinition is completed and extendingthrough the delivery and acceptance testingof the software system. The Plan isprepared for the ICAM Program Office and alltechnical participants in the developmentwork, and is used to assure that technicalactivities have been adequately planned andthat all participants understand the workingenvironment and objectives. Potentialreaders may be assumed familiar with generalsoftware design, programming, and testingactivities. The Plan should be preparedsoon after the Requirements Document, andshould be approved by appropriate officialsbefore significant development begins.

ANNOTATED OUTLINE


1 . 1 Summary

(Identify the software system involved and its generalcharacteristics. Summarize the scope and purpose of thisdevelopment plan, pointing out significant methods, cri-teria, specifications, and techniques being used to achievetimely completion of a quality software product.)

1 . 2 Environment

(Identify the development organization and its institu-tional members. Describe the envisioned utilization of thesoftware and prospective user installations. Also describethe supporting hardware and software components, and the in-tended degree of portability.)

1.3 References

(List previously or concurrently issued documents thatare applicable to the software and this development plan.)

2. DEVELOPMENT TASKS

(Describe the planned development work as distincttasks and define the deliverable results of each. State thetechnical disciplines involved, and briefly describe thosewhich are unique or innovative. List the individual pro-ducts and milestones, and the anticipated start and comple-tion times for each task or significant activity. Identifythe responsibility of each participating organization in thecompletion of each milestone. State the expected allocationof personnel time and other resources to individual tasks.Show the sequence, timing, and interdependence of all tasksthrough appropriate charts or figures.)

- 64 -

3.

DEVELOPMENT ORGANIZATION

(Describe fully the organizational units, principalpersonnel, roles and responsibilities for the development ofthe proposed software. Indicate the significant resources,particularly computer equipment and software, to be providedby each party. Define the work procedures and relationshipsplanned among the parties in the development. Relate theinformation to the defined tasks and to the stages in thesoftware life cycle.)

4.

DEVELOPMENT AND QUALITY ASSURANCE METHODOLOGY

(Referring to the tasks defined above, describe fullythe technical criteria, specific techniques, tools and sup-port software, and development practices to be used. Definethe quality assurance principles and practices. Define sig-nificant day-to-day working methods. List and describe ma-jor reviews, audits, inspections, and demonstrations. De-fine all quantitative and objective measurement or assess-ment techniques to be used.)

5.

STANDARDS

(Describe the application of specific standards citedin the References and others to be developed for this pro-ject. Include standards on programming languages, develop-ment tools, program structuring and coding conventions,testing, and documentation.)

- 65 -


LEFT BLANK

- 66 -

SYSTEM/SUBSYSTEM SPECIFICATION

The System/Subsystem Specificationdescribes in detail the functional specifi-cations, operating environment, and designcharacteristics for the system or subsystem.Derived from the Requirements document, theSystem/Subsystem Specification specifies a

design strategy for the overall system. Itpresents the logic flow of the entire sys-tem/ subsystem, thus showing an integratedview of the system or subsystem dynamics.This technical document is used by thesoftware designer, the analysis team, theprogrammer, and the configuration manager.It is one of the first documents to beprepared during the Design stage in thesoftware development life cycle.

- 67 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the system's specifications and other designelements for the system.)

1.2 Environment

(Identify the system developer, potential manufacturinguses, hardware and software environment, and possibleoperating sites for the system.)

1.3 References


* Development Plan;* Feasibility Study;* Cost/Benefit Analysis;* Requirements Document;* Other relevant project documentation.)

2. SPECIFICATIONS

2.1 Description

(Describe in general terms the system or subsystem be-ing designed. Describe how this system or subsystem relatesto other systems or subsystems. Discuss potential applica-bility and adaptability of this system to other manufactur-ing activities.)

- 68 -

2.2 Funct ions

(Specify the system/subsystem functions, and show howthey satisfy specific functional requirements.)2.3

Per formance

(Specify performance requirements in qualitative andquantitative terms. Describe the flexibility and adaptabili-ty of the system/subsystem to changes in performance re-quirements . )


3 . 1 Equipment

(Identify and describe the equipment required for theoperation of the system/subsystem. Include present equip-ment configuration, as well as new equipment required tosupport specific functional requirements.)

3.2 Support Software

(Describe any support software required for thesystem/subsystem being developed -- for example, a utilitydump routine, a sort/merge package, or system testingroutines. If changes are required in the support software,describe the nature, status, and availability date of suchchanges . )

3 .

3

Interfaces

(Describe relevant interfaces with other software.)

3.4

Security and Privacy

(Describe any security and privacy requirements for thesystem/subsystem.

)

- 69 -

3 . 5 Controls

(Describe the operational controls imposed on thesystem/subsystem. Identify sources of these controls.)

4. DESIGN CHARACTERISTICS

4 . 1 Operations

(Describe operating characteristics that are specificto the computer system facility where the newsystem/subsystem will be operational. For example, if thecomputer system facility is primarily oriented toward batchprocessing, the design of new applications should take thatoperating factor into consideration.)

4.2 System/Subsystem Logic

(Describe the logic flow of the entire system/subsystemin the form of a flowchart (or other graphical representa-tion). The flow should provide an integrated presentation ofthe system/subsystem dynamics, of entrances and exits, com-puter programs, support software, control, and data flow.)

5. PROGRAM SPECIFICATIONS

5.1 Program Specification (Identify by Name)

(Specify this program component of theSystem/Subsystem. Describe the system/subsystem functionthe program will satisfy, and describe the design charac-teristics of the program.)

- 70 -

5.2 Program Specification (Identify by Name)

(Describe the remaining computer programs insimilar to the paragraph above.)

manner

- 71 -


LEFT BLANK

- 72 -

PROGRAM SPECIFICATION

The Program Specification describesprogram designs in sufficient detail to en-able program coding. In contrast with theSystem/Subsystem Specification, whichdescribes the system's programs on a generallevel, the Program Specification addresseseach individual program and its modules. Itspecifies the functions, performance re-quirements, interfaces, operating environ-ment, and design characteristics of eachcomputer program to be constructed. Thistechnical document is used by the softwaredesigner, the system analyst, and the pro-grammer for constructing the software. TheProgram Specification is prepared during theDesign stage of the software developmentlife cycle, following review and conditionalapproval of the System/Subsystem Specifica-tion.

- 73 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the specifications of the computer program,and briefly describe the function that this program per-forms.)

1.2 En v ironment

(Identify the system designers, potential manufacturingusers, hardware and software environment, and possibleoperating sites . )

1 . 3 References


* Development Plan;* Feasibility Study;* Cost/ Benefit Analysis;* System/Subsystem Specification;* Other relevant project documents.)

2. SPECIFICATONS

2.1 Program Description

(Provide a general description of the program, includ-ing the system/ subsystem function that this program willsatisfy, the algorithm and the programming language to beused, required utility program and interfaces, and relation-ships to other system/subsystem components. Identify anyprogram features that would restrict modification, or anyfeature that may create maintenance problems.)

2 .

2

Functions

(Specify the functions of the program to be developed.If the program in itself does not fully satisfy a

system/subsystem function, show its relationship to otherprograms which in aggregate satisfy that function.)

2 . 3 Performance

(Specify performance criteria in quantitative terms.Describe the tests that the program must be subjected to be-fore it is deemed acceptable. Describe the flexibility andadaptability of the program to changes in performance re-quirements . )


3 . 1 Equi pment

(Identify and describe the equipment required for theoperation of the program. Describe the present equipmentconfiguration, and indicate the changes needed to supportspecific functional requirements, as reflected in theSystem/Subsystem Specification. Identify otherhardware/software on which the program can run.)

3.2 Support Software

(Describe any support software required for the programbeing developed -- for example, utility routines and systemsoftware. Indicate if a Database Management System (DBMS)is being used, and whether the program being developed is an

application program under the DBMS. If the support softwarerequires changes, describe the nature, status, and availa-bility date of such changes.)

3 . 3 Interfaces

(Describe relevant interfaces with other software com-ponents.)

- 75 -

3.4

Storage

(Specify the storage requirements for the program, in-cluding any constraints and conditions. Include informationabout internal, offline, and auxiliary storage require-ments . )

3.5

Security and Privacy

(Describe any security and privacy requirements for theprogram . )

3 .

6

Control

s

(Describe program controls, and identify sources ofthese controls .

)

4. DESIGN CHARACTERISTICS

4.1

Operating Procedures

(Describe the operating procedures for the program.These procedures are specific to the computer system facili-ty where the program will be implemented. Identify thesoftware tools to be used in the implementation of the pro-gram, and any other special requirements that should be not-ed.)

4.2

Inputs

(Describe the inputs to the program. Specify thesource and type of data, its expected volume and frequency,its means of entry, and provisions for maintaining necessaryprivacy and security.)

4.3

Program Logic

(Describe the logic flow of the program, showing theinteractions among program modules, input/output relation-ships, and general data flow.)

- 76 -

4.4 Outputs

(Describe each output from the program, includingdesired format, expected volume and frequency, dispositionof products, and security and privacy considerations.)

4.5 Data Base

(Describe the logical and physical characteristics ofany database used by the program. If the database ismanaged by a Data Base Management System (DBMS), thendescribe the database in terms of the DBMS used.)

- 77 -


LEFT BLANK

- 78 -

DATA SPECIFICATION

The Data Specification is a technicaldocument that specifies the characteristicsof the data used by the programs beingdesigned. It includes a description of thephysical and logical characteristics of thedata, and pertinent information about input,access, updating, and processing. Intendedfor use by technical personnel, such assoftware designers, system analysts, andprogrammers, the Data Specification isprepared during the Design stage of thesoftware development life cycle. The DataSpecification is particularly important fordefining large aggregates of data such asparameter tables or databases.

- 79 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the scope and characteristics of the data,and briefly describe the general functions of the applica-tion software using the data.)

1.2 Environment

(Identify the system developer, the hardware andsoftware environment, the pertinent manufacturing functions,and the possible operating sites of the software system.)

1.3 References


* Requirements Document;* System/Subsystem Specification;* Program Specification;* Other relevant project documents.)

2. DESCRIPTION

2.1 Identification

(Identify aggregate data structures or databases anddescribe the nature of the data, such as whether it is tem-porary, experimental, or test data.)

- 80 -

2.2

Using Software

(Identify all programs that will use this data. Providethe name, the release, and the version number of thesoftware .

)

2 .

3

Conventions

(Describe the labelling and tagging conventions that a

programmer or an analyst must know to use the data specifi-cations . )

2.4

Special Instructions

(Provide any special instructions for personnel whowill be generating, accessing, or modifying the data. Asnecessary for brevity, provide references to the appropriatesoftware .

)

2.5

Support Software

(Give the name, function, major operating characteris-tics, and instructions for all support software directly re-lated to the data, including DBMS software. Cite supportsoftware documentation. Examples of support software are:

* Database management system;* Data dictionary/directory system;* Storage allocation software;* Data loading software;* File processing software.)

3. LOGICAL CHARACTERISTICS

(Describe each data item or field as well as the asso-ciations that constitute the logical organization of thedata as viewed by prospective manufacturing users. Defineand explain the structure of the data, the relationshipsamong data items, constraints on and criteria for access andupdating, and the characteristics pertaining to integrityand validity.)

- 81 -

PHYSICAL CHARACTERISTICS4 .

4.1

Storage

(Specify the computer storage requirements, con-straints, and machine-dependent factors involving the data.Include information about internal storage areas, devicesrequired for peripheral storage, physical storage manage-ment, and offline storage requirements.)

4 . 2 Access

(Describe indexes, access methods, and access paths asappropriate for the intended physical storage approach.)

4.3 Design Considerations

(State design considerations for handling the data, in

order to achieve such goals as efficient access and relia-bility. Include information about potential implementationstrategies to satisfy design considerations.)

- 82 -

STRATEGIC TEST PLAN

The Strategic Test Plan describes con-cepts, criteria or standards, tools, andstrategies for testing the software system.The developer produces it at the end of theDefinition stage of the software life cycleand addresses it to internal management(especially programming, design, and testingsupervisors) and to ICAM Program Officemanagers

.

- 83 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the software characteristics and thedeveloper’s general testing strategy.)

1 . 2 Environment

(Name the testing organization or group and describethe testing environment, including kinds of personnel aswell as support hardware and software. In particular, com-pare the testing environment to the planned operating en-vironment . )

1 . 3 References

(List applicable references, including

* the Requirements Document against which the softwarewill be tested; and

* publications that give more detail about proposedtesting concepts, strategies, or methods.)

2. TESTING CONCEPTS AND CRITERIA

(Discuss the overall testing approach, concepts, andcriteria that will assure production of quality softwarethat meets its objectives and requirements. State how muchof the testing will be simulation, and how much actualoperation of the software. Define the level of functionaltest ing--i . e . ,

the features of the software the developerwill test. Also define the level of structuraltest ing--i . e . , how completely the developer will examine thesource code. Demonstrate that the planned testing will as-sure the acceptability of the software with respect to itsrequirements and specifications. Establish the criteria thedeveloper will use to judge the quality, performance, and

- 84 -

function of the software. State the quantitative criteriafor determining acceptability in such major areas as timing,throughput, accuracy, and storage.)

3. TOOLS

(Describe any tools that the tester plans to use inchecking out the software system. If such tools are notcurrently available in the testing environment, discussplans for getting them.)

4. STRATEGIES

4 . 1 Kinds of Tests

(Name and describe the distinct types of testingplanned for the software. Discuss the purpose and specificmethodology for each of these tests, and tell how thedeveloper will use specific tools for each of them. Discussthe applicability of different tests to general requirementsof unit testing, integration testing, system testing, andacceptance testing.)

4.2 Test Data Generation

(Describe fully the methods and procedures for produc-ing test data for each major area of testing.)

4.3 Documentation

(Discuss general plans for documenting test proceduresand results, and for disseminating test sets for reuse.)

- 85 -


LEFT BLANK

- 86 -

DETAILED TEST PLAN

The Detailed Test Plan specifies de-tailed test data and procedures, as well ascriteria for reducing and evaluating testdata. Its audience includes personnel fromthe ICAM Program Office and managers andtechnical staff from the contracting com-pany. The developer produces this plan dur-ing the Design and Programming stages of thesoftware life cycle.

- 87 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the implementation of the general testingstrategy that has been accepted for determining whether thesoftware meets its requirements and specifications.)

1 . 2 Environment

(Identify the testing organization, facilities, andsites, as well as support hardware and software. Describeany prior testing not governed by this plan and state theresults that have or should be obtained.)

1 . 3 References


* Previously published documents on the project--especially the Strategic Test Plan, the RequirementsDocument, and the three Specifications;

* Documentation concerning related projects; and* Standards and guidelines such as FIPS publications,

DIDs, and DoD manuals.)

2. PLAN

2.1 Software Description

(Briefly describe the modular components and functionsof the software system which have influenced the selectionof locations, resources, and schedule described below.)

- 88 -

2.2

Mi lestones

(List the locations and dates for each major testingactivity .

)

2.3

Testing Activities

(Describe the activity at each test site, including thetest function (e.g., system test), the test location, theparticipating organizations, a detailed schedule of testingevents, a comprehensive list of equipment, support software,and personnel necessary to perform the test, required testmaterials (including the software, its documentation, testinputs and sample outputs, and test control software andworksheets), and plans for providing any training that isnecessary before personnel can perform the tests.)

3. SPECIFICATIONS AND EVALUATION

3.1 Specifications

(List the scheduled tests, and state the functional re-quirements and specifications that each addresses. Alsodescribe the progression from test to test.)

3.2 Methods and Constraints

(Describe and justify any modifications of the metho-dology and strategy specified in the ’Strategic Test Plan.Indicate anticipated limitations on the test due to testconditions, such as interfaces, equipment, personnel, anddata bases . )

3.3

Evaluat ion

(Describ'e the rules for evaluating test results, con-sidering such factors as the range of data values, the com-binations of input types, and the maximum number of allow-able halts or interrupts. Specify manual and automatedtechniques for manipulating the test data into a form suit-able for comparison with required results.)

- 89 -

3.4 Documentation

(Fully describe how the developer will document thetesting of the software system.)

4. TEST DESCRIPTIONS

«

(Fully describe each test, including the control overinsertion of inputs, sequencing of operations, and recordingof results, the input data and commands, the intermediatemessages, the expected output data, and the step-by-stepprocedures for performing the test, including test setup,initialization, and termination.)

- 90 -

TEST ANALYSIS REPORT

The Test Analysis Report describes thetests conducted and gives the results,describes the method used in analyzing testresults, presents the demonstrated softwarecapabilities and deficiencies for review,and evaluates the status of the software in

light of the test results. This report isprepared for technical and management per-sonnel, both in the developing organizationand in the ICAM Program Office. The TestAnalysis Report is prepared for system test-ing and for acceptance testing, after eachtest has been completed. System Testing isdesigned to compare the software system toits original goals and objectives, while ac-ceptance testing is the process of comparingthe finished software to its initial re-quirements, as stated in the RequirementsDocument

.

- 91 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the application and general functions of thesoftware being tested and the test analysis documentedhere.)

1.2 Environment

(Identify the system developer, the potential manufac-turing users, the supporting hardware and software, and thepossible operating sites of the software system. Describethe manner in which the test environment may be differentfrom the operational environment and the effects of thisdifference on the tests.)

1 . 3 References

(List applicable references, including:

* Requirements documents;* System/Subsystem, Program, and Data Specifications;* User 1 s Manual

;

* Operations Manual;* Program Maintenance Manual;* Development Plan;* Strategic Test Plan;* Detailed Test Plan;* Other relevant documentation.)

2. TEST RESULTS AND FINDINGS

(Provide detailed information for each test separatelyin paragraphs 2.1 through 2.n.)

- 92 -

2.1

Test (Identify)

(Describe testing scenarios, techniques and tools, t e s

t

strategies, and test results and findings.)2.2

Test (Identify)

(Present testing information on second and succeedingtests in a manner similar to 2.1.)

3. SOFTWARE FUNCTION FINDINGS

(Identify and describe conclusions that can be drawnfrom all test results with respect to the functions definedin the Requirements Document and Specifications.)

3.1 Functions (Identify)

(Briefly describe the function and software being test-ed, and the tests themselves. Include the range of datavalues tested. Report findings, including deficiencies,limitations, and constraints.)

3.2 Function (Identify)

(Report findings,, on the second and succeeding functionsin a manner similar to paragraph 3.1.)

4. ANALYSIS SUMMARY

4 . 1 Capabilities

(Summarize the capabilities of the software as demon-strated by the tests. If tests were conducted to demon-strate that one or more performance requirements are ful-filled, then compare the results with these requirements.Assess the effects that any difference in the test environ-ment as compared to the operational environment may have hadon this demonstration of capabilities.)

- 93 -

4.2 Deficiencies

(Describe the deficiencies of the software as demon-strated by the tests. Describe the impact of each deficiencyon the performance of the software and the overall impact onperformance of all detected deficiencies.)

4.3 Recommendations and Estimates

(Estimate the time and effort required to correct eachdeficiency. State how urgent the correction is, how it

should be made, and who should make it.)

- 94 -

SOFTWARE VALIDATION REPORT

The Software Validation Reportdescribes methods used and results obtainedin final validation of software before itsdelivery for installation at prospectiveuser sites. The Report is used by the ICAMProgram Office to confirm that the softwarewill serve its intended application effec-tively and that development has progressedsatisfactorily. The Report also serves toinform software users and other ICAM parti-cipants of validation practices and theireffectiveness.

- 95 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the software involved, its functions,characteristics, and intended applications. Brieflydescribe the scope of the validation that was performed.)

1 . 2 Environment

(Identify the developer and the validation partici-pants. Define the supporting hardware and software for thesystem, the prospective user sites, and any qualificationsor restrictions on the validation that relate to intendedinstallations and applications.)

1.3 References

(List applicable documents, including the RequirementsDocument, Development Plan, and pertinent specifications.)

2. VALIDATION TASKS

(Describe the validation process as distinct tasks, in-cluding a summary of the progressive stages of testing.Summarize the disciplines and procedures of each validationtask, and clearly indicate the pertinent results to be de-tailed later in this Report. Indicate the role or responsi-bility of each participating organization in each task.Summarize the resources used, and depict the sequence,schedule, and interdependence of all tasks performed.)

- 96 -

3.

VALIDATION ORGANIZATION

(Describe fully the organizations, principal personnel,and their responsibilities in the complete validation ef-fort. Define significant working procedures and relation-ships, with reference to the tasks described abpve.)

4.

VALIDATION RESULTS

(Describe fully the results obtained from each distinctvalidation task, and state the conclusions warranted bythese results in regard to software quality, validity, reli-ability, and overall readiness for delivery to prospectiveusers. Include a detailed description of the methods actu-ally used in each task, including personnel involved, timeand other resource expenditures, sqpport tools and back-ground data used, progressive or partial results and theirdisposition in the final outcome of each task. Summarizetesting results, and also define the efforts made and as-surances produced from correlation of source code and docu-mentation, audits of source code with respect to all appli-cable standards, physical configuration audits, interfaceaudits, reliability measurement and prediction, correlationof test cases and requirements, simulations, shake-down ordry runs, etc.)

5.

DISCREPANCIES AND VALIDATION

(List completely in summary form all the discrepanciesidentified by the validation process and their proposedresolution. Provide a conclusive statement concerning thepresent readiness of the software for ICAM use and the ex-tent to which ICAM requirements and development objectiveshave been met.)

- 97 -

THJS PAGE DELIBERATELY

LEFT BLANK

98

SOFTWARE SUMMARY

The Software Summary (FIPS 30)describes a computer program or automateddata system on Standard Form 185. Its audi-ence includes technical and managerial per-sonnel from the contractor's own company,from the ICAM Program Office, from otherICAM participants, and from other manufac-turing industries. The contractor shalldeliver it after he has completed testingand validating the software described by thef orm

.

- 99 -

1. INSTRUCTIONS FOR COMPLETING THE SOFTWARE SUMMARY

(Obtain Standard Form 185 from the nearest GSA supplyoffice and follow the instructions on the back of the form,with the following exceptions:

10. Appl icat ion Ar ea . Within the area labeled"Specific” describe the software's particularmanufacturing application in the developer's in-dustry.

13. Narrative . Besides the recommended information,suggest potential applications of the softwarein other industries.)

- 100 -

USER'S MANUAL

The User's Manual describes softwarefunctions in user-oriented terminology. Themanual serves as the primary reference docu-ment for the user. This document is preparedto serve users with a wide range of techni-cal sophistication and experience, includingnovices, managers, and computer scientists.The developer begins preparing the User'sManual during the Programming stage of thesoftware development life cycle. The manualis revised and updated until the softwarehas been validated, and the resulting finaldocument is delivered with the system.

- 101 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the application and general functions of thesoftware .

)

1 . 2 Environment

(Identify the system developer, the potential manufac-turing functions, the hardware and software interfaces, andthe possible operating sites of the software system.)

1 . 3 References

2. DESCRIPTION OF SOFTWARE APPLICATION

(Describe the basic concepts, goals, and design philo-sophy of the software system. Discuss its functional andperformance capabilities, its basic elements, the functionsit performs, and the services it allows. Describe thestructure of the software, the role of each component in theoperation of the software, and the operational relationshipsof this software to other software. If used, graphicalrepresentations can be appended to this section. Describe indetail the system's processing operations, relationshipbetween input and output, and databases or data files thatare referenced, accessed, or maintained by the software.Describe minimal equipment configuration required for run-ning the software.)

- 102 -

3. PROCEDURES AND REQUIREMENTS

3.1

Commands and Procedures

(Name and describe:

* Operating commands;* Protocols used

;

* System calls to support software or utilities, re-quired parameters and formats;

* Characteristic responses and potential problems;* Special operating requirements.)

3.2

Initiation

(Describe step-by-step procedures required to initiateprocessing .

)

3.3

Input

(Describe preparation requirements for input data: fre-quency, volume limitation, input formats, priority and secu-rity restrictions, sample input, and all necessary parame-ters. In interactive processing where input is minimal,this section may simply highlight any factor s--such as datastandards .or CRT screen posit ions--that may demand user at-tention. High-volume interactive situations may requiresuch information as limits on file size or number of users.)

3 .

4

Output

(Describe the requirements relevant to each output.Include such information as use, frequency, output format,and sample output. For interactive processes, an item likeoutput format might simply indicate CRT screen positions fordata . )

3.5

Error and Recovery

(Describe conditions that will generate error codes ormessages. Include simple and detailed explanations of errormessages along with ways to isolate and correct particularproblems. Indicate procedures to be followed by the user toensure that restart and recovery procedures can be used.)

- 103 -


LEFT BLANK

-ion-

OPERATIONS MANUAL

This document is used by technicalstaff. The Operations Manual describes in

detail the software's operating characteris-tics and its associated environment, so thatcomputer operators and programming personnelcan run the software. The Operations Manualis drafted during the Programming stage, andit is refined and updated until the systemis validated. This manual is delivered withthe system.

- 105 -

ANNOTATED OUTLINE

1. GENERAL INFORMATION

1 . 1 Summary

(Summarize the general functions and operating charac-teristics of the software, including its purpose and use.)

1.2 En v ironment

(Identify the system developer, the potential manufac-turing functions, the hardware and software interfaces, andthe possible operating sites of the software system.)

1 . 3 References

(List Applicable references, such as:

* User ' s Manual

;

* Program Maintenance Manual;* Installation Guide;* Other pertinent documentation on the project.)

2. OVERVIEW

2.1 Software Organization

(Describe the software's inputs, outputs, required datafiles, and sequence of operations. Describe, with the aid of

charts or diagrams, how various modules are interrelated.Identify the software's constraints, such as priority of ex-ecution, input or output requirements, dependence on othersoftware, and security. Describe groupings within thesoftware . )

- 106 -

2.2 Program Inventory

(Identify each program by title, number, and mnemonicreference.)

2.3 File Inventory

(Identify each file that is referenced, created, or up-dated by the system. Include the title, the mnemonic refer-ence, storage medium, required storage, and access informa-tion.)

3. DESCRIPTION OF RUNS

(Provide explicit instructions that the computer opera-tor or programmer must follow for running the software.Specifically indicate where operator intervention is re-quired. Include such information as:

* Protocol required to access a system;* Operating system interaction, if any;* Job control cards (or instructions) required to set

up a runstream (or a session);* Calling instructions and sequences for program

modules

;

* Calling instructions and sequences for supportsoftware, such as utilities, system routines, orother application routines;

* Input and output preparation requirements;* Operator messages, and required action;* Restart and recovery procedures.)

4. NONROUTINE PROCEDURES

(Provide any information necessary concerning emergencyor nonroutine operations, such as switchover to a back-upsystem in case of failure, and procedures for turnover tomaintenance programmers.)

- 107 -

REMOTE OPERATIONS5 .

(Describe the procedures for running the

through remote terminals.)program

PROGRAM MAINTENANCE MANUAL

The Program Maintenance Manual explainsin detail the programs, their operating en-vironment, and their maintenance procedures .

This document is prepared for the mainte-nance programmers and the operators. It

provides them with necessary technical in-formation for understanding the programs,their operating environment, and theirmaintenance procedures. Preparation of theProgram Maintenance Manual should begin dur-ing programming and verification, and itshould be refined and updated until the sys-tem is validated. This document is deliveredalong with the system and other documenta-tion.

- 109 -

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the characteristics, functions, special re-quirements, and procedures for maintaining the system.)

1 . 2 Environment

(Identify the maintenance team, the potential manufac-turing functions, the hardware and software environment, andthe possible operating sites of the software system.)

1 . 3 References

(List applicable references, including:

* User's Manual* Installation Guide* Operations Manual* Test Plans and Reports* Other relevant project documentation.)

2. PROGRAM DESCRIPTIONS

(In this section, identify all the programs in thesoftware system, and individually describe each program com-ponent. )

2.1 Program Description (Identify by Name)

(Identify the program to be maintained. Describe theproblem that the program solves, and the solution methodused, including algorithm chosen and programming language in

which the program is implemented. Describe input require-ments, processing features, expected output, storage media,interfaces with other software, and procedures to run the

- 110 -

program, including loading, terminating, and error handling.Explain programming conventions used.)2.2

Program Description (Identify by Name)

(Provide the description, as stated above, of each pro-gram in the software system.)


(This section describes the overall operating environ-ment of the software system.)

3.1 Hardware

(Identify the equipment required for the operation ofthe system. Include information about the processor used,storage media, peripheral devices, and special features.)

3.2

Support Software

(Identify the support software required for each pro-gram. Identify the operating system, compiler or assembler,database management system, report generator, or any othersoftware required by this program.)

3.3

Database

(Identify and describe the database used, and refer torelevant documentation on the database, including a dataelement directory.)

-Ill-

4. MAINTENANCE PROCEDURES

4.1

Verification Procedures

(Describe the verification procedures to check the per-formance of the program, either in general, or followingmodification. Include a reference to test data and pro-cedures.)

4.2

Error Conditions

(Describe error conditions (including those not previ-ously documented elsewhere), their origin, and the recom-mended method for correcting them.)

4.3

Special Maintenance Procedures

(Describe any special procedures required for maintain-ing the software. Include procedures and recommended fre-quency for preventive maintenance. Identify and describespecial programs used for maintenance, such as file restora-tion programs and file purger.)

4.4 Listings and Flowcharts

(Refer to or else append the listing and flowcharts.)

4.5 Regression Testing

(Regression Testing is performed after a significantchange is made to the software, either for functional im-provement or for repair. Its purpose is to determine if thechange has affected adversely other parts of the software.In this section, describe the tests performed and the testdata and test cases used.)

- 112 -

INSTALLATION GUIDE

The Installation Guide specifies op-tions, parameters, and procedures for confi-guring and loading the software in the vari-ous planned operating environments, and forperforming acceptance tests on the installedsoftware system. This Guide is prepared forcomputer operations technical personnel inthe user’s organization. Initial preparationof this document begins during the Program-ming and Verification stage. It is revisedduring Testing and Validation and deliveredwith the system and other system documents.

ANNOTATED OUTLINE


1 . 1 Summary

(Summarize the purpose and general functions of thesystem, identify the resources and materials needed, andsummarize the general requirements and procedures for in-stalling the system.)

1 . 2 Environment

(Identify the system developer, potential manufacturingusers, hardware and software environments -- including in-terfaces -- and possible operating sites of the softwaresystem .

)

1.3 References


* User's Manual;* Operations Manual;* Maintenance Manual;* Related Project Documentation.)

2. OVERVIEW

2.1 General System Description

(Describe the basic concepts, goals, and design philo-sophy of the software system. Discuss the functions it per-forms, its capabilities, and its characteristics. Explainany particular feature that will be crucial to successfuland efficient installation.)

- 114 -

2.2 Installation Planning and Preparation

(Describe administrative and preparatory requirementsand procedures, such as

* Choosing an approach to installation, i.e., instal-ling immediately, installing in phases, or parallelprocessing ;

* Scheduling computer time, and preparing the computersite and application environment;

* Organizing an acceptance testing team;

* Devising training plans for maintenance personnel;

* Checking that all system documentation is complete;

* Performing required conversion; and

* Making provisions for backup and recovery, safety,and security . )

3. INSTALLATION

3.1 General Requirements for Installation

(Describe the basic requirements for installing thesoftware, such as:

* Hardware : List minimum hardware requirements for in-stallation, e.g., mainframe (including model andseries), memory requirements, storage requirements,peripheral equipment, such as disk drives, tapedrives, line printers, communication processors, andother special equipment.

* Software : Specify other software required, such as

operating system (include version and level re-quired), compiler (include version and level re-quired), utility routines, database managementsoftware, and other special purpose software.

* Dat a : Specify names of databases (or files) that thesystem will need to use; indicate sources of dataand procedures for collecting data.

* Installation Options : Define and discuss options orparameters available for optimizing or tailoring thesoftware to a given type of computer system or ap-plication environment. Provide guidelines on properselection of parameters and options. Describe stan-dards implications fully.

* Other Requirements : Indicate other requirements forinstalling the software system.)

3.2 Software System Components

(Enumerate and describe all the components of thissoftware system. For each component, program, or module,describe its functions and its relationship to other com-ponents . )

3 •• 3 Procedures

(Describe, in sequence, the procedures for installingthe system:

* Describe required initialization processes, such asinitializing files or databases, creating a diction-ary or a directory, etc.

* Provide detailed instructions on how to proceed withthe installation, including the order in which thesoftware components should be installed, the parame-ters that must be used, and the required equipmentand support software.

* Include procedures for linking components and com-piling the software. Describe the sequence of execu-tion by component names, and list and describe thedatabase, or files, generated and accessed.

* Provide detailed procedures for correcting installa-tion errors, and for starting over again.

* Provide directions for installing the system afterthe first time

.

* Identify typical problems that may occur during in-stallation, describe how each problem is solved, andrecommend means of preventing future problems ofthis kind.)

3.4 Installation Demonstration

(Describe installation demonstrations or tests that areconducted prior to formal acceptance testing, to ensure thatthe system has been correctly installed and is operational.)

4. ACCEPTANCE TESTING

(Acceptance Testing is performed to verify that thesoftware system operates successfully in a live environment,that it satisfies objectives and performance criteria de-fined in the Requirements Document, and that the system canserve the intended application. Describe fully thie accep-tance testing scenario, include requirements on the accep-tance testing team, types of tests conducted, procedures,and expected results of the testing.)

5. TRAINING

(Describe in detail the types of formal training re-quired by the operator and user of this system.)


LEFT BLANK

- 118 -

MAINTENANCE PLAN

The Maintenance Plan describes the ob-jectives, organization, responsibilities,criteria, and schedule for maintenance ofimportant ICAM software. It is preparedafter completion of the software develop-ment, and is used by the ICAM Program Officeto monitor maintenance effort and to informsoftware users of the maintenance being pro-vided .

ANNOTATED OUTLINE


1 . 1 Summary

(Identify the software systems covered by this Plan,and their general functions and characteristics. Summarizethe scope of this Maintenance Plan, pointing out the levelof effort planned, objectives and criteria, and considera-tions important to users.)

1 . 2 Environment

(Identify the maintenance organization or contractor,and other participants in maintenance effort. Identify thesupporting hardware and software involved in the maintenanceactivity. )

1 . 3 References

(List applicable documents, including the MaintenanceManual and other manuals issued for the software.)

2. MAINTENANCE TASKS

(Describe the planned maintenance work as distincttasks for each software system covered by this Plan. Definethe conditions and criteria applicable to initiation andcompletion of each task, the basic disciplines required, andthe type of results expected. Identify the role and contri-bution of each party in the maintenance effort, and theresources provided where known or estimable. Show the se-quence, schedule, and interdependence of all tasks.)

- 120 -

3. MAINTENANCE ORGANIZATION

(Describe fully the organizations, principal personnel,and responsibilities for maintenance. Define the necessaryprocedures, working relationships, and intercommunication.)

4. MAINTENANCE METHODOLOGY

(Describe the technical criteria, techniques, tools andsupport software, and maintenance practices to be used, un-less these are fully and accurately treated in the Mainte-nance Manual. Define day-to-day working methods, audits,inspections, and other quality assurance practices.Describe the application of specific standards to mainte-nance tasks and results. Define documentation produced toinform users of software changes and to maintain accurateconfiguration data on the software system. Define quantita-tive criteria for maintenance performance and software qual-ity.)

- 121 -


LEFT BLANK

- 122 -

APPLICATION REPORT

The Application Report tells how a

given user organization applies the softwaresystem in its particular environment: whatfunctions the software performs, what bene-fits it produces, and what special or gen-eral purpose changes or improvements the or-ganization has developed. Written for bothtechnical and managerial personnel, the Ap-plication Report is prepared during theOperation stage of the software life cycle.Its purpose is to give other potential usersa clear example of the functions, flexibili-ty, and value of the software system.

- 123 -

ANNOTATED OUTLINE

1. GENERAL INFORMATION

1 . 1 Summary

(Name the software and generally describe its applica-tion in the user's organization.)

1 . 2 Environment

(Identify the user's company and the operating site ofthe software. Name and describe the equipment on which thesoftware runs, and describe interfaces with other software.Briefly describe the kinds of personnel who operate thesoftware system.)

1 . 3 References


* The Feasibility Study and Cost/Benefit Analysis forthe software system;

* Related applications software or documentation;* Documents from related projects; and* Relevant standards or guidelines, including FIPS


2. THE SOFTWARE PACKAGE

(Describe the software package in its delivered form.Use the general topic headings described below.)

- 124 -

2.1

Function

(Describe in detail the particular application of thesoftware. What manufacturing function does it automate, andin what overall context?)

2 . 2 Adjustments

(Give the parameters used in installing the software on

the user's own system. Specify relevant hardware andsoftware interfaces.)

2.3 Modifications

(Describe in detail any modifications that were neces-sary before the new software could run on the user's system.Append or refer to the documentation for any new versions ofmodules or programs.)

2.4

Training

(Tell how the user organization trained its personnelto use the new software. Describe the kind of personnel whowere trained and the kind, amount, and cost of training. Ifpart of this training was necessary only for enhancementsdeveloped by the user, separate the training informationinto two distinct parts--one for the delivered softwarepackage, and another for user-developed enhancements.)

3. ENHANCEMENTS

(Describe any special features developed by the user toenhance the performance or usefulness of the software. Ap-pend or refer to the documentation for installing and usingthe software system.)

- 125 -

EVALUATION4.

4.1 Cost/Benefit Analysis

(Evaluate in detail the costs and benefits of thesoftware. Include both nonrecurring costs like capital in-vestment, software conversion, and training, and such recur-ring costs as salaries, maintenance contracts, and supplies.Compare these costs with quantifiable benefits like costreduction due to reduced resource requirements, improvedoperating efficiency, increased productivity, and smallererror rates . )

4.2 Overall Evaluation

(Considering both tangible and intangible factors, es-timate the value of the software system to the user organi-zation . )

- 126 -

IDEF

Model

- 127 -


LEFT BLANK

- 128 -

'Sj

5

t-H eg tO Lrt \0rH rH rH iH iH rH

a a a a a «

turH rH l 1 1 1 1 1 to rH eg to rH eg to rri-H

31

i

1 l 1 1 l 1 rHS3

i

CsJ eg eg rO to to ro<

1

i

1

1

i

1

1

1

1

i

1

1

i

l

1

i

1

l

<1

<1

<:

i

<i

i

<i

i

<i

<f 1

J<

f

- 129 -

The

ICAM

Software

Documentat

ion

System

accomplishes

the

production,

control,

review,

and

distribution

of

ICAM

results

pertinent

to

computer

programs

and

data,

as

tasks

in

the

software

life

cycle.

Documentation,

as

used

here,

refers

to

textual

and

associated

graphic

information

c CO

o ri

r*» •H 3 CO 3r-l p 3 3 3P 3 ED 3 •H 3

• CJ rH 3 0 P d 3 >c •pH 3 •H 3 P 3 3 £o 3 3 a ft 3 3•H P O 3 3 3 Op CO 3 •H 3 CO 3 O P •rH CO3 3 P 3 CO 3 ft 3 EDCJ 3 3 O 3 •pH P ED 3 33 3 > 3 > d 3 3 d 3 P* Xi p 3 £ ft O 3 P3 P Cm P 3 a •H P 3

O O 3 o d o P O >>d CO 3 CO •H cj 3 3 P3 d •H > P CJ EC3 c ft 3 3 M d

3 CO . 3 3 O •rH 3p 3 q CO O o a ft 3 33 A •pH 3 p ft H p 3 3ft CO d o O 3 p >3 a) 3 r\ 3 >» ft O -H CJ O•H rH P U) d H O d < 3 o

CO bO O H ft3 d a 3 3 3 ft 3 3 p(U O >» •H ft 3 CO O P 3 oP a p -P P 3 3 33 •pH CO 3 3 3 d aft d H •H 3 3 d ft rH 3B 3 •pH rH 3 r* 3 O p CJ 3O O p > 3 3 O O •rH 3o rH •pH

CO d 3 > CO3 ft

3 ft 3 3 O 3 3 H >> P 3o CO ai ED CO d CJ 3 3 Pft P ft O 3 c P O d P

O 3 3 3 3 O ED 3>> 0) 3 ft rH P 3 P 3 3 CO

i—

1

d o ft 3 3 P d3 •pH r\ 3 •H P 3 3 ft 3rH h ft c

0

3 3 P O 0J 3o 3 cd rH 3 3 •pH P CJ 3CO a cj 3 Cm O 3 CO 3

3 •rH 3 CO •H ft -rH 3 3is •pH

PrHft § § 3 ft

O PPd3

O•H

ft a 3 £2 P P . O PP CO 3 P 3 3 3 a ft 3o CO #• O 3 3 O 3 P•H 3 CO co #\ ft a ft 3 3 3P ft 3 3 3 3 p. ft 3 3> a d O rH rH o >> 3 S

O 3 •pH ft 1—

1

rH d O pft o rH ft 3 P 3 3 3 CJ CJ

3 3 o 3 •rH 3 > O d oP (I) 3 cj rH 3 3 3 P dP •H •rH 3 •rj d 3 rH 3P cm 3 o •H O 3 3O O >> •rH 3 3 K a 3P 3 rH O 3 ft P 3 3 3 d

H 3 CO P O ED 3d CO 3 ft 3 d •H 3 3 O3 3 CJ co 3 d P o 3 3CO o •rH d 3 3 3 *H 3 POftd Si §

33>P ft3 3

aCO

ft E • P 3 O 3 a 3o 3 3 ED 3 O P a 3 CO P

O O 3 O cj •H 3 O p •

CO •rH •rH O 3 3 3 d o ft CJ s i—

1

3 P P •H ft d P 3 o 3 3 3 33 cd p O CJ p d -H 3 3 d

r* p pj 3 f« 3 3 3 P ED O0) 3 3 P CO ft P 3 3 H 3 O aCO <D O 3 p •H 3 3 O 33 Q ft 3 3 O 3 3 3 CJ CJ ft a

§

3 3 3 P P O ? -H 3cj

o•pH

O § d P P ft!>>ft £

ft

co 3 PCO

s d 3 o CO 3 CO pH O Eh p o >>p e rH d 3 3 •H P co 3 M COX P CO •H CJ 3

P cd 3 3 3 3 3 • s 3 33 3 d 3 3 cd O 3 . fi p P oO 3 cd 3 3 •rH •H 3 3 u Eh •pH

ft P 3 > 3 ft d a 3 O ft3 P ED 3 3 ED d 3

d 0) 1 ft O H P P P o • p<0 ,3 3 o rH 3 3 CO 3 3 (3 CO 3d P 3 CO O •H 3 O >s ft 3 P 333 CO

•pH

P33

a 3 3ED 3 S

P 3 CJ o ft o d d <2 O 3 CJ

3•HPEh

cd

a3P

3a

Od §3ft

33

Oft

NODE.

TITLE:

DCC/A-OTI

CONTEXT—

OPERATE

ICAM

SOFTWARE

DOCUMENTATION

ICAM

Program

Requirements

—

i

CO

CD TJ

b ^3 cd

> 'G

£ §O -PCO CO

Gc s g o go < o o•H O -H G -H-p M -P O -Pcd cd •H o3

 o g G cu

oP- 3o O

O CO

COo o o G o G -hn co Q On O M Q

OrH oa CO

CO -po -p o

rH G<p CO <5, o•H <u o GPi K M Oh

§

G co

9 oo o* as o< wo <uM «

- 13 ?-

NODE:

ITITLE:

DOC

/A-0

PROVIDE

ICAM

SOFTWARE

DOCUMENTATION

Technology

Information

- 1 ? 4 -

£ C03 0) cti

•U •H uc > O,03 03 03

03 e P4 o+j 3 o03 O »-l <dC

0

O Oa P 44 ^3

CVJoAono

U 03

3 03

T3 -Ho aVJ OP o

- 1 3 5 -

DGC/Al

DEVELOP

SOFTWARE

AND

SOFTWARE

DOCUMENTATION

Looked

at

together,

the

decompositions

of

[All]—

"Produce

ICAM

Software

Documentation

present

a

highly

structured

view

of

the

software

life

cycle.

The

model

does

not

show

the

many

informal

iterations

that

contribute

to

successful

software

development.

It

CO

rH 4*1 •

o CO wG d ftG i—

f

(2 hcd 2 0) oj

o gX 42 po CO o s

Li cd O -pO 4=> Li d COt> d 01

<V 0) d Li gCO <v cd O o

«M a> ft •rH

42 Li ftM CO d cd

2 2 a> S Po o 42 cd $2

Li Li ft -P <D

42 O CO g-P g 2

£ CO oO g 3 r—

i

obO Li » 42 cd cd 0)cd P •H i

—i G

g d 3Li d ?

42 o P O co> P bO E •H

2 G 0) rH 2e!

«M P •H g cd <i)

o •H d ft ft Op cd o •H M

42 CO 0) rHCJ 4^ G i

—i P

ai CO r*

f—

1

•H < oCO H

ftp2o

3goft

ftO H

bDcd

•Hd E

ai 2 -H O PG p H

1 ft •H CO

G o cd P 2CO Li •H g

cd •H O CO

42 rH p o Li

d E "H ft Ocd O g P o Op m d 42 o cd

CO > H P a) Li

E a> 2 d P•rH •rH O d G

s> 2 2 •H 42 u4 Li p g Po cd oft ft 42 E E 4201 o P -H H p

NODE:

TITLE:

D0C/A11T

PRODUCE.

ICAM

SOFTWARE

DOCUMENTATION—

TFXT

- 137 -

D0C/A11

I

PRODUCE

ICAM

SOFTWARE

DOCUMENTATION

I

4-> 4-1

3 34-* 33 E 4-t

3 3 3 H XE 3 a 3 33 3 o 3 3U TJ T3

O - H 3Q 3 3 > X

M X *rt 4-J

3 3 4-4 3X 3 o

3 o rt 4-t

3 4-)

4-1 3 •• 3<4-1 O 3 r—

1

o X T—

t

O oCO 3 4-J •H i-l

3 4-1 4-t

3 3 3 •H 3x: X CJ X) O4J •H 3 O

i—

i

44 33 i—t •H 3•H •rt 3 3 3

> bO w3 •r-t 33 3 33 3 • 33 X 3 33 4J 3 u a •

O 4-1 3 3O r 3 3 3 OM r-t -3 3 •rt •H

3 3 •rt O 3 4->

T3 V-4 r-t 4-t •rt

rt O 4-t bO w 3i—

1

E 3 3 O3 O 3 a 3

3 o -3 SO >-i 4-1 3 o4-4 •rt 3 •rt o

4-) 3 3 34-1 3 O •H 33 3 >3 3 3) t-4 4-t

4-1 3 3 3 3 Xl-l X rHo3E O•rt 4J 4->

o-cCO

° i3 aCO CD

Cl) 'O

co ca

CD

CJ

3M-4

3CD CO

O

0) C/J

4-t

3•rt •

rHi—I 0)

O TJ

CO 0)

3S*.

3 3B u

3 3 3 3 33 rH 34 *rl rH 33 X a •rt

3 3 39 O o o 3O •H 3 rH 3r—

t

r-t 3 3 <1) CJ

3 34 3 X m 343 CL i—

1

•H r-i

3 3 bO rH 3E 3 3

33 3 •H 3t-i 44 4- l-l O 4-t

bO 3 3 3 •H 33 3 3 4-4 •rt

•rt 3 o 3- 3 l-l

T3 rH •rt 3 4-1 3o 4-1 3 3 O

o u •H 3 )-i

w 4-t 3 r-H E 3IXi 3 O o 3 3

o 3 u 3 3

u3CD

a33

oE HO

6 3

3 3 rHX ^ 'HH co Ss

c/J 3•H

3x 34-f 3

O3 r3•H CO

3 3bO ,334-1 rH3 i—

1

•H3 So3 33 3

3X4 -3O H34-1 •

3 CD

3 bo4-t 33 4->

O 3

>, 3M 3

O•rt

4->

O3 3O

I

3 TJ

bO -HO 4-J

i—I 3o E3 *->

X o3 4-1

3 3H H

_1_-1 T 1

D0C/A11F

J'lTLt.

FEG

detailing

control

INTERFACES

rOC/Alll

TITLE:

ANALYZE

NEEDS

ICAM

Standards

11v

Definition

- 140 -

DCC/Aii:

!

DEFINE

SYSTEM

REQUIREMENTS

I

-1 42 -

MODE

ITITLE:

~

D0C/A114

PROGRAM

AND

VERIFY

.ODE

TITLE:

DOC/A115

INTEGRATE,

TEST,

AND

VALIDATE

- 144 -

node

[title

POC/Allfe

OPERATE

AND

MAINTAIN

- 145 -

4J

OoT3OM(X

LU.J

r-

tij

OO

D0C/A13

CONFIGURE

DOCUMENTS

FOR

ICAM

I

- 1 4 7 -

ITITLE:

D0C/A2

|

ADMINISTER

SOFTWARE

DOCUMENTATION

SYSTEM

C2

ICAM

Standards

eawC/3

•Ho

i-

t-

UJ

QO

-14 8 -

D0C/A21

I

REVIEW

PROJECT

DOCUMENTATION

- 1 4 Q

NODE:

D0C/A22

T,TLE:

evaluate

software

documentation

system

-1 ^

*

V,0D£:

DOC/A23

fiTL£:

DEVELOP

PROPOSED

ICAM

SOFTWARE

DOCUMENTATION

STANDARDS

ICAM

Software

Documentation

Standards

coars

Wcc

2cI—

I

t-<

wCOCO

a<Cu

sa

- 152 -

Dissemination

DOC/

A32

MANAGE

DISSEMINATION

TASKS

(TITLE

DOC/

A33

I

PROVIDE

INFORMATION

SERVICES

•or

LU

ao2

it

-155

DOC/A34

'

DISTRIBUTE

DOCUMENTS


LEFT BLANK

- 156 -

GLOSSARY FOR DOC-MODEL

GLOSSARY FOR DIAGRAM A-0

Box [ A-0 . 0 ] PROVIDE ICAM SOFTWARE DOCUMENTATION : Develop,produce, control, review, and distribute ICAM SoftwareDocumentation

.

[A-0. Oil] LIFE CYCLE RESULTS OF ICAM PROJECTS : Results suchas software products, documents, reports, etc. that arepertinent to the current project, but were produced byother ICAM projects.

[A-0.0C1] TECHNOLOGY INFORMATION ; State of the art informa-tion in pertinent technology, especially in computerand software technology. This type of information pro-vides guidance on methodology, quality criteria, feasi-bility of an approach, etc.

[A-0.0C2] ICAM PROGRAM REQUIREMENTS : Standards, plans andpolicies, and resources constraints, as applied tosoftware development.

STANDARDS : Standards that are already approved, and areapplicable to ICAM software development. These stan-dards require technical compliance. They may beFederal standards or guidelines, Air Force or ICAMstandards, etc. For example, MIL-STD 490, FIPS 38, DoDStandard 7935. 1 -S , the ICAM Software DocumentationStyle Guide and Content Guides, etc.

POLICIES AND PLANS : Plans, organizational policies, andregulations that may govern the software operations ofaffected organizations. These require general compli-ance, and may originate from the Federal Government,the Air Force, ICAM organizations, contractor or sub-contractor organizations, etc.

RESOURCES CONSTRAINTS : Constraints due to limitationsof manpower, money, time, hardware/software facilities,etc. Other resources constraints include budgetary,contractual, or managerial considerations.

[A-0.0C31 NEEDS INFORMATION : Information that indicates ap-proaches and needs for software documentation. Includ-ed would be contract specifications, technical articles

- 157 -

on documentation, conference results from documentusers, and special task force reports on user needs.

CONTRACT SPEC IFICATIONS : Contract specifications con-sist of specific requirements which are dictated by thesponsor funding the project. These specifications maystate in very general terms the nature, objectives, andevaluation criteria for the project. They may alsocontain specific requirements for compliance with ICAMpolicies, standards, and regulations.

USER NEEDS : Project requests, statements of users’ re-quirements, problem statements, etc.

[A -0.001] ICAM SOFTWARE DOCUMENTS ( SOFTWARE DOCUMENTATION )

:

Textual information and associated graphics intendedfor human use, as opposed to those which are solely forcomputer input and execution. Software documentationis the technical and project information intended even-tually for wide dissemination, and specifically orient-ed toward the development, design, maintenance, and useof ICAM computer programs and systems. Specifically in-cluded are: feasibility studies, program specifica-tions, manuals, program listings, and instructional ma-terial required to produce and use reliable andtransferable software products. Excluded from thisclass of documents are the budget and program docu-ments, contracts, management correspondence, and basicmanufacturing and engineering results.

[A-0.002] PROPOSED ICAM SOFTWARE DOCUMENTATION STANDAR DS

:

Technical specifications for software documentationthat are proposed by ICAM organizations after evaluat-ing the effectiveness of the Software DocumentationSystem and identifying problems in responding to users'needs .

[A-0.003] INFORMATION ON DISSEMINATION : Management informa-tion on the complete body of ICAM Software Documentsthat are available for dissemination, including, forexample, indexes to available software documents.

[A-0.0M1] ICAM MEANS AND RESOURCES : All resources needed or

used to perform a task, including people that dotasks--e.g., developers or ICAM manager s--and automatedtools— e.g. , a FORTRAN analyzer, IDEF, or a report gen-erator .

- 158 -

GLOSSARY FOR AO

BOX [AO. 1 ] DEVELOP SOFTWARE AND SOFTWARE DOCUMENTATION ; Theemphasis in this stage is on the software documentsproduced in conjunction with software development.Good software management practices dictate that docu-mentation should be produced during the softwaredevelopment process, and not as an afterthought ; thisbox reflects that philosophy by showing the twoprocesses as integrated.

BOX [AO. 2] ADMINISTER SOFTWARE DOCUMENTATION SYSTEM : Per-formed by the ICAM Program Office, this function encom-passes such oversight activities as formally reviewingfor compliance with contracts and standards, overseeingand evaluating the effectiveness of the operations ofthe Software Documentation System, and proposing techn-ical specifications for documentation standards.

BOX [AO. 3] DISSEMINATE SOFTWARE DOCUMENTS : This activity in-cludes not only the distribution of software documents,but also the management of information about thesoftware collection.

[A0.1C4] POST -DELIVERY REDIRECTIONS : Feedback from the ICAMProgram Office, affecting ICAM Software Documentation.Redirections are usually issued after the Software Do-cumentation has been delivered to the ICAM Program Of-fice and undergone formal review for compliance.Redirections provide guidance to developers for res-tructuring or modifying noncompliant document s— thosethat do not conform to technical or contractual re-quirements .

[AO. 101 ] SOFTWARE PRODUCTS : Actual programs, listings,tapes, associated data files, etc.

[AO. 102] MASTER DOCUMENTS FOR REVIEW AND ACCEPTANCE : Thesedocuments have been delivered by a contractor ordeveloper for ICAM review and acceptance. After finalacceptance, they are placed under configuration con-trol.

[AO. 103] PRODUCTION COPIES : These reproductions of masterdocuments are prepared for dissemination.

[AO. 203] DISSEMINATION GUIDANCE : Directions for dissemina-tion of ICAM Software Documents and related services.Such guidance might include dissemination lists,schedules, and requirements.

- 159 -

[AO. 204] MASTER DOCUMENTS FOR DISSEMINATI ON : These documentscomply with contract specifications and ICAM standards,and are therefore reproduced for dissemination to otherprogram participants and to the public.

[AO. 311] ORDERS FOR DOCUMENTS : Formal requests for documentsfrom the ICAM user community.

[A0.3M1] AIR FORCE AND CONTRACTORS : These people are respon-sible for disseminating the software documents. Theactivity may be performed by a group within ICAM ordelegated to a responsible organization such as NTIS.

[A0.2M1] A_I_R FORCE PROJECT MANAGERS AND USERS : The ICAM Pro-gram Office within the Air Force has the primaryresponsibility for administering the Software Documen-tation System. It is aided by feedback from the usercommunity

.

[A0.1M1] SOFTWARE DEVELOPERS : These people are responsiblefor developing software and software documentation.They may be either contractors or members of ICAM or-ganizations .

- 160 -

GLOSSARY FOR A1

BOX [ A 1 . 1 ] PRODUCE ICAM SOFTWARE DOCUMENTATION : The actualproduction of documentation during the software lifecycle. Note that the focus is on software documents,not the actual software products.

BOX [A 1.2] MANAGE QUALITY AND CONFIGURATION : This is the"formal" internal review cycle performed by the con-tractor. Technical quality control for documentationis exercised throughout software development. Redirec-tion, in the form of suggested modifications or gui-dance, is supplied to the developing group before finaldelivery to ICAM sponsors.

BOX C A 1 .33 CONFIGURE DOCUMENTS FOR ICAM : The final prepara-tion of documents for delivery to the ICAM Program Of-fice and subsequent dissemination. Preparation focuseson physical organization and control requirements forICAM .

[A1.1I2] USER NEEDS : See [A-0.0C31: Needs Information. In-cluded are project requests, statements of users' re-quirements, problem statements, etc.

[ A 1 . 1 C 5 ] PRE -DELIVERY REDIRECTIONS : The internal technicalguidance issued by the d e v e 1 ope r s / co n t r ac t or s ,

due toinconsistencies, problems, or inadequacies found in thesoftware documentation processes. Such redirection is

given before the documents are submitted for formal re-view and acceptance by the ICAM Program Office.

[ A 1 .202] QUALITY SOFTWARE DOCUMENTS : These documents’ haveundergone thorough inspection as well as quality as-surance review, and have been judged not only to complywith technical and contractual requirements, but alsoto meet the contractor's highest criteria for excel-lence .

-16 1 -

GLOSSARY FOR A 1 1

BOX [ A 1 1 . 1 ] ANALYZE NEEDS ; The developer studies the exist-ing system to determine how new software can solvecurrent problems. This initial stage in the softwarelife cycle involves an assessment of present technologyand the formulation of various approaches based on ex-isting technology and on descriptions of comparablesystems. After evaluating each of these systems fortechnical feasibility and economic benefits, the con-tractor recommends one of them for development.

BOX [All. 2] DEFINE SYSTEM REQUIREMENTS : Using the softwaresolution that was recommended at the conclusion of theanalysis stage, the contractor specifies detailed re-quirements for the functions, data, performance, porta-bility, and modularity of the software. He will alsospell out auxiliary software requirements such as util-ity routines, specific compilers, or a database manage-ment system. He will often consult future users of thesystem, and he may simulate the operating environmentin order to "test out” requirements.

BOX [ A 1 1 . 3

]

DESIGN : Design consists of preliminary design,detailed design, and the planning of these activities.The preliminary design covers the overall system andproduces preliminary specifications for system/ subsys-tems, programs, and data. Feedback from a review pro-cess helps refine these documents, which then guide thedevelopment of detailed specifications for each aspectof the software system. Using these specifications,the design team prepares a Strategic Test Plan outlin-ing testing strategies and methodology.

BOX [All. 4] PROGRAM AND VERIFY : Following standard program-ming practices, the developer writes, debugs, and teststhe computer programs designed to satisfy ICAM needs.At the same time he begins preparing system documenta-tion, including drafts of the Operations Manual, User’sManual, Program Maintenance Manual, and InstallationGuide. When he has tested all program units, heprepares a Detailed Test Plan according to the metho-dology and strategy outlined in the Strategic TestPlan.

BOX [All. 5] INTEGRATE, TEST , AND VALIDATE : Perform tests,

analyze test results, and validate them against systemspecifications. If tests are unsuccessful, requestreprogramming or file a Problem Report. When tests aresuccessful, release Test Analysis Reports on

- 162 -

integration testing and system testing, and finaldrafts of the User's Manual, Operations Manual, ProgramMaintenance Manual, and Installation Guide.

BOX [All. 6] OPERATE AND MAINTAIN : At this stage the develop-er works with the user to install, operate, and main-tain the developed software. After installing the sys-tem, he prepares a Test Analysis Report on acceptancetesting. The organization responsible for maintainingthe system prepares a Maintenance Plan for the user.After adapting the software to his own environment, theuser evaluates the system and prepares an ApplicationReport on his particular applications of the softwareand on any enhancements he may have developed.

[All. 101] ANALYSIS DOCUMENTS : The analysis of needs producesa Definition Plan, a Feasibility Study, and a

Cost/Benefit Analysis. Informal analysis data includeAlternative Software Solutions and Technical Feasibili-ty Evaluations.

[All. 201] REQUIREMENTS DOCUMENT : The Requirements Documentdefines functional, data, performance, and other re-quirements of the proposed software system.

[All. 301] DESIGN DOCUMENTS : Specific design documents in-clude a Development Plan, a System/Subsystem Specifica-tion, a Program Specification, a Data Specification,and a Strategic Test Plan. Informal design data in-clude Problems and a Preliminary Design.

[All. MO 1 ] PROGRAMS AND RELATED DOCUMENTS ; Actual programsand listings, along with a formal Detailed Test Plan,informal documents noting Problems and Unit TestResults, and Draft Manuals.

[All. 501] SOFTWARE SYSTEM AND DOCUMENTS : Formal test and in-tegration documents include Problem Reports, a SystemTest Analysis Report, a Software Validation Report, a

Software Summary, an Installation Guide, a User's Manu-al, an Operations Manual, and a Program MaintenanceManual. Informal data include Integration TestResults .

[All. 601] OPERATIONS DOCUME NTS : These documents include a

Maintenance Plan, a Test Analysis Report on acceptancetesting, an Application Report, and Problem Reports.Informal operations data include Maintenance Require-ments and Operation and Usage Experience.

GLOSSARY FOR A 1 1

1

BOX [All 1.1] DEFINE PROJECT SCOPE AND PLAN DEFINITION TASKS :

After receiving a statement of user needs, an analysisproject team meets to define the scope of the problem.The project team may vary throughout the life cycle ofthe project development effort, but at this stage itgenerally involves users as well as developers. Thisteam has the responsibility of determining whethersoftware can solve the problem as stated, whether theorganization has the resources to do the job, andwhether the problem needs to be subdivided (or subcon-tracted) for development purposes. The team refines theuser's statement of needs before formulating a plan andsetting the bounds for the problem under study. Itdescribes the objectives, states the assumptions, andformulates a set of evaluation criteria for furtheranalysis. Of primary interest during this planningstage are the documenting activities. The project teamprepares a Definition Plan to cover the activities ofneeds analysis and requirements definition.

BOX [ A 1 1 1 . 2 ] FORMULATE TECHNICAL APPROACHES : Having deter-mined that the problem is solvable, the project teamnext formulates technical approaches for satisfying theobjectives of the software development project. It

assesses current technology in the relevant field, not-ing in particular any descriptions of comparable sys-tems. The team then documents possible technical ap-proaches, including in its report the applicablesoftware assessments.

BOX [All 1.31 EVALUA TE PERFORMAN CE AND FEASIBILITY : The pro-ject team evaluates each of the alternative softwaresolutions to determine its technical f ea s ib i 1 i t y--i . e .

,

its capability of meeting user requirements with avail-able technology and methods of operation. In addition,the team determines the performance and operationalfeasibility of each solution— i .e . , its ability to fitthe operational pattern and resources of the organiza-tion. In some cases, the team may use simulation, or

modeling, to "exercise" each software solution, andthen use the simulation reports in evaluating perfor-mance and operational feasibility.

BOX [ A 1 1 1 . 4 ] ASSESS COST S AND BENEFITS : For each of the al-ternative software solutions, the developer must evalu-ate not only recurring and nonrecurring costs, but alsoquantifiable and intangible benefits.

- 164 -

BOX [ A 1 1 1 . 5 ] PREPARE PROJECT RECOMMENDATION : After the pro-ject team evaluates the technical feasibility and bene-fits of each of the alternative software solutions, itcompares their risks, uncertainties, and sensitivity tochanges. It then prepares a Feasibility Study recom-mending one software solution to the development teamand to management.

[ A 1 1 1 . 1 C 1 ] ICAM STANDARDS : Applicable ICAM Standards includegeneral technical guidelines as well as the ICAMSoftware Documentation Style Guide and the ICAMSoftware Documentation Content Guides for the Defini-tion Plan, Feasibility Study, and Cost/BenefitAnalysis

.

[A111.101] DEFINITION PLAN : The Definition Plan covers allthe activities of needs analysis and requirements de-finition. It tells whether these activities will in-volve automated tools or formal reports and other docu-mentation. It identifies resources, organizations,methodology, and standards for specific definitiontasks, and it schedules milestones, reviews, anddelivery dates for major ICAM Software Documents.

[ A 1 1 1 . 2C 3 1 COMPARABLE SYSTEMS INFORMATION : Information aboutsystems which resemble alternative software solutions,but which may have been used in a different environmentor designed for different purposes.

[All 1.201] ALTERNATIVE SOFTWARE SOLUTIONS : Alternativestructures and methods for satisfying the identifiedobjectives of the system development project.

[ A 1 1 1 . 30 1 ] TECHNICAL FEASIBILITY EVALUATIONS : This technicalpart of the Feasibility Study evaluates the abilitiesof the alternative software solutions to satisfy userrequirements with available technology and methods ofoperation .

[ A 1 1 1 . 40 1 ] COST / BENEFIT ANALYSIS : The Cost/Benefit Analysisgives managers, designers, and users detailed estimatesof projected costs and benefits of alternative piecesof software. It analyses both recurring and nonrecur-ring costs, and tangible and intangible benefits.

[A111.501] FEASIBILITY STUDY : The Feasibility Study summar-izes the findings of the analysis activity. Itdiscusses the goals and needs of an organization andcompares possible ways to reach those goals. Itrecords the technical feasibility evaluations of alter-native software solutions and recommends a particularsoftware system as the best to meet the technical and

- 165 -

economic requirements of the software development pro-ject.

C A 1 1 1 . 50 2 ] COST / BENEFIT ANALYSIS : The formal documentpresenting the information identified in [A111.M01]:Cost/Benefit Analysis.

- 166 -

GLOSSARY FOR A1 1

2

BOX [ A 1 1 2 . 1 ] SPECIFY FUNCTIONAL REQUIREMENTS : Identify anddefine the system functions that are required of theproposed software. These requirements may indicate theintended operating environment and the user activitiesto be supported

.

BOX [ A 1 12.2] SPECIFY DATA REQUIREMENTS ; Identify relevantdata items or aggregates, and describe the necessarytechnical characteristics for data collection andstorage

.

BOX [ A 1 12.31 SPECIFY PERFORMANCE AND OTHER REQUIREMEN TS : De-fine such performance characteristics as timing for jobturnaround, response time in an interactive environ-ment, and requirements for accuracy, validation, edit-ing, and security. These requirements should reflectresults of any simulations performed during this stage.

BOX [ A 1 12.4] SPECIFY DESIGN CONSTRAINTS : After defining thesystem requirements, the project team specifies anyfundamental design standards, and identifies and docu-ments any constraints on the design process. For exam-ple, some mathematical software to be used might re-quire a particular FORTRAN compiler.

BOX [ A 1 12.51 INTEGRATE AND EVALUATE RESULTS : Using the in-formation produced during requirements analysis, refinecost estimates for the project and combine the informa-tion about requirements into the Requirements Document.

[ A 1 1 2 . 1 C 1 ] I CAM STANDARDS : These standards include generalguidelines for requirements analysis as well as theICAM Software Documentation Style Guide and the ICAMSoftware Documentation Content Guide for the Require-ments Document .

[ A 1 12. 1 C 2 ] DEFINITION PLAN : See [ A 1 1 1 . 1 0 1 ] .

[A112.101] FUNCTIONAL REQUIREMENTS : The Functional Require-ments initially define the software, including its re-quirements and operating environment. They compare ex-isting and proposed methods of performing the requiredfunctions, and they identify projected improvements,possible impacts, and specific functions of proposedsoftware products.

[ A 1 12.201 ] DATA REQUIREMENTS : The Data Requirements describethe data in technical terms. They identify static and

- 167 -

dynamic data elements and tell what kind of informationthe user and the developer collect to characterizespecific data elements.

C A 1 12. 30 1 D PERFORMANCE AND OTHER REQUIREMENTS : A descriptionof such required performance characteristics as timing,accuracy, security, validation, flexibility, andresponse to contingencies. When applicable, Perfor-mance and Other Requirements should include a simula-tion or analysis report.

[A112.401] DESIGN CONSTRAINTS : Constraints on softwaredesign, perhaps including language specification, basicand special design standards, and interfaces with theexisting system.

[ A 1 12.501 ] REQUIREMENTS DOCUMENT : The Requirements Documentincludes the functional, data, performance, and otherrequirements of the proposed software system. For in-dividual descriptions of the separate components, see[ A 1 1 2 . 1 0 1 ] ,

[ A 1 1 2 . 20 1 ] , and C A 1 1 2 . 30 1 ] .

- 168 -

GLOSSARY FOR A 1 1

3

BOX [ A 1 1 3 • 1 ] PLAN DEVELOPMENT : Plan the development of thesoftware project from preliminary design through accep-tance testing.

BOX [ A 1 13.2] PERFORM PRELIMINARY DESIGN : The developer pro-duces and documents an overall preliminary design ofthe software system, emphasizing general specificationsof the system’s internal construction. The projectteam, including intended users, validates the require-ments documents, and the designers use feedback fromthis review cycle to sketch out software modules andcomponents

.

BOX [ A 1 13.33 PREPARE SYSTEM / SUBSYSTEM SPECIFICATION : Thedesign team analyzes the performance trade-offs ofvarious algorithms and prepares detailed structural andfunctional specifications for each system/subsystem.After defining the internal architecture of thesoftware, the team documents the system/subsystemspecification, which provides a frame of reference forthe remainder of the design.

BOX [ A 1 13.4] PREPARE PROGRAM SPECIFICATION : Using thesystem/subsystem specification, the designers specifyand document individual program modules and their in-teractions .

BOX [ A 1 13.53 PREPARE DATA SPECIFICATION : Define the logicaland physical characteristics of the data. This defini-tion may identify sources, methods of collection, andstorage properties.

BOX [A 1 13.6] EVALUATE DESIGN AND PLAN TESTING : Review thefinal design and prepare a Strategic Test Plan outlin-ing strategies and methodology for testing the softwaresystem

.

[A113.1C1] I CAM STANDARDS : These standards include generalguidelines for software design as well as the ICAMSoftware Documentation Style Guide and the ICAMSoftware Documentation Content Guides for the Develop-ment Plan, the System/Subsystem Specification, the Pro-gram Specification, the Data Specification, and theStrategic Test Plan.

[A113.101] DEVELOPMENT PLAN : The Development Plan specifiesthe organizational units responsible for particulartasks and identifies products and milestones. It

- 169 -

allocates necessary resources and personnel for eachtask, describes the methodology for development andquality assurance, and schedules reviews and deliverydates for software products and documents.

C A 1 1 3 - 20 1 ] PROBLEMS : Problems detected during preliminarydesign. The project team reports them to the project’squality control personnel, who either resolve the prob-lem or file a Problem Report. Problems can also be re-ported from any other design activity.

[ A 1 1 3 . 20 2 ] PRELIMINARY DESIGN : A general outline for theSystem/Subsystem Specification, the Program Specifica-tion, and the Data Specification.

C A 1 1 3 . 30 1 ] SYSTEM / SUBSYSTEM SPECIFICATIO N : This documentgives detailed information about the operating environ-ment, design characteristics, system and subsystem in-terfaces and relationships, logic, dynamics, supportsoftware requirements, and control and data flow ofproposed software.

[ A 1 13.^01 ] PROGRA M SPECIFICATION : Specifically directed to-ward programmers, this document gives detailed charac-teristics of the proposed software: its functions, its

operating environment, its logic and flow, the rela-tionships among its modules, and the design features ofeach module

.

[ A 1 13.501 ] DATA SPECIFICATION : This document states thestandards, conventions, and quality requirements of theproposed data, and specifies its logical and physicalc har a c t e r i s t i c s-- i nc 1 u d i n g methods of creation, collec-tion, storage, access, maintenance, updating, and pro-tection. The document also specifies the software toperform these functions.

C A 1 1 3 . 60 1 ] STRATEGIC TEST PLAN : This document outlines theconcepts, criteria or standards, tools, strategies, andmethodology for testing the software system. It speci-fies what part of testing will be simulation and whatpart actual operation of the software. It identifiesbroad tests (like unit testing), giving their purposesand specifying what documentation they require.

- 170 -

GLOSSARY FOR A 1 1

4

BOX [ A 1 1 4 . 1 ] CODE, DEBUG,AND UNIT TEST : Using standard pro-

gramming languages, the programmers write executablecode to satisfy the program specifications produced in

the design stage. Debugging involves finding andcorrecting errors introduced during the coding process.When debugging is finished, the programmers test indi-vidual program modules to ensure that they are logical-ly correct for the particular testing environment.This unit testing, which the programmer documents inthe Unit Test Results, verifies that the module has nosignificant problem or logical error to impede its use.Errors discovered in testing may feed back to the cod-ing, or even to the design stage. Programmers shouldtake care to document carefully each of these threeprogramming stages.

BOX [ A 1 1 4 . 2 ] PREPARE MANUALS : Using the newly tested codefor individual program modules, write drafts of manualsfor installation, operation, maintenance, and usage ofthe system. Revise the manuals each time a change incode affects their usefulness.

BOX [ A 1 14.31 REVIEW VERIFIED PROGRAMS AND COMPLETE TESTINGPLAN : Review programs for correctness and conformanceto programming standards in the ICAM Software Documen-tation Style Guide. Prepare a Detailed Test Plan.

[ A 1 1 4 . 1 C 1 ] ICAM STANDARDS : General guidelines for program-ming as well as the ICAM Software Documentation StyleGuide and the ICAM Software Documentation ContentGuides for the Unit Test Analysis Report, the User'sManual, the Operations Manual, the Program MaintenanceManual, the Installation Guide, and the Detailed TestPlan.

[ A 1 14. 1 C 2 ] DEVELOPMENT PLAN: See [ A 1 1 3 . 1 0 1 ] .

[A114.101] PROBLEMS : Problems detected during coding, debug-ging, or unit testing. These informal reports go tothe project's quality control personnel, who eitherresolve the problem or file a formal Problem Report.Other activities during programming and verificationcan also report Problems.

[ A 1 1 4 . 1 0 2 ] UNIT TEST RESULTS : This informal document recordsthe results of each unit test. It analyzes testresults and presents demonstrated capabilities and de-ficiencies for review.

- 171 -

[A114.103] UNIT TESTED PROGRAMS : Programs (along with theirlistings) that have "passed” unit tests, and are con-sidered logically correct within that testing environ-ment.

[A114.201] DRAFT MANUALS : First drafts of a User’s Manual,an Operations Manual, a Program Maintenance Manual, andan Installation Guide. Programmers will continue toupdate all this documentation until the software systemis validated

.

[ A 1 1 4 . 30 1 ] DETAILED TEST PLAN : The Detailed Test Plan re-views previous testing history, identifies particulartests, and specifies test locations and environments.It states the functions that need to be tested anddescribes appropriate test cases, including criteriafor evaluating the thoroughness of the testing as wellas the performance of the software. It matches teststo requirements, specifications, and functions of thesoftware system. It gives a detailed schedule ofevents, including test dates, test sites, and anynecessary special arrangements (e.g., freeing up a

block of computing time). It describes the tools need-ed for testing, and specifies how to compile test data.

[ A 1 1 4 . 3 0 2 ] VERIFIED PROGRAMS : Unit tested programs that havegone through a final review for correctness.

- 172 -

GLOSSARY FOR A 1 1

5

BOX [ A 1 1 5 . 1 3 PERFORM INTEGRATI ON TESTING : Integrate indivi-dual programs into the specified overall system andtest them to make sure that each of them still workswell when linked with other programs into an integratedsoftware system.

BOX [ A 1 1 5 . 2 ] PERFORM SYSTEM TESTING : Test the integratedsystem to make sure that as a whole it will performproperly in the specified operating environment.

BOX C A 1 15.33 PERFORM FINAL VALIDATION : Analyze system test-ing results in terms of design specifications. Noteminor problems and errors for correction by the pro-gramming team. Major problems with the original designor functional specifications may require a Problem Re-port.

BOX [A 1 15-43 PREPARE SYSTEM FOR DELIVERY : Physically preparethe system for delivery to the user. When appropriate,prepare tapes and disk packs, set up files in the prop-er sequence, and assemble system components fordelivery

.

[A115.1C1] I CAM STANDARDS : General guidelines for testing aswell as the ICAM Software Documentation Style Guide andthe ICAM Software Documentation Content Guides for theTest Analysis Report, the Problem Report, the SoftwareSummary, the User’s Manual, the Operations Manual, theProgram Maintenance Manual, and the Installation Guide.

[ A 1 1 5 . 1 C 2 ] DETAILED TEST PLAN : See [A114.301].

[A115.101] PROBLEM REPORT : The Problem Report records anyanomalies in the testing of the system. Depending onthe seriousness of the problem, the report may feedback to any of the four preceding stages--needsanalysis, requirements definition, design, or program-ming. Any testing or validation activity may result ina Problem Report

.

C A 1 1 5 . 1 02 ] INTEGRATION TEST RESULTS : This report documentshow well the individual program modules perform afterthey have been integrated into a system.

[ A 1 1 5 . 1 0 3 3 INTEGRATED SYSTEM : The integrated system includesall the program modules, each of which has passed in-tegration testing.

- 173 -

[A115.201] SYSTEM TEST ANALYSIS REPORT : The System TestAnalysis Report records the performance of the systemas a whole during its test runs. It describes thetests, inputs, outputs, and performance of the softwaresystem in the testing environment, and it compares thisperformance to the expected performance of the softwarein the actual operating environment.

[A1 15.202] TESTED SYSTEM : The software system (including itslistings) that has passed system tests and is ready tobe packaged for delivery to the user or the ICAM Pro-gram Office.

[A115.3I2] LISTINGS : The code for the tested software sys-tem.

[ A 1 15.3C3] REQUIREMENTS AND SPECIFICATIONS : Relevant ICAMstandards and all previous project documents that arenecessary for final validation. Included are the ICAMSoftware Documentation Style Guide and Content Guides,the Feasibility Study, the Requirements" Document, allthe specifications, and both test plans.

[A115.301] SOFTWARE VALIDATION REPORT : When the developerhas successfully completed the system testing of hissoftware-, he prepares the Software Validation Report tocertify that the system functions reliably and meetsboth its specifications and the requirements of theuser environment.

[ A 1 15. 40 1 ] INSTALLATION GUIDE AND USER 'S ,OPERATIONS ,

ANDPROGRAM MAINTENANCE MANUALS : Although the programmersdraft these manuals during programming, they do notrelease them until after final validation. At thispoint the texts of the manuals are final, but the docu-ments themselves must still be physically prepared be-fore delivery to the ICAM Program Office. The Instal-lation Guide specifies how, and under what conditions,the software system may be installed. For example, itmay specify that two tape drives are necessary to loadall the modules in, or that it expects certain commandsfrom the console. The Operations Manual gives direc-tions for operating the system in its specified en-vironment. The Program Maintenance Manual describesfor the maintenance programmer the functions of thesoftware system, its operating environment, and anynecessary maintenance procedures such as programmingconventions, verification procedures, and error correc-tion procedures. The User's Manual describes for usersthe functions performed by the software. It shouldcontain information on how to use the software, and itshould serve as a reference document for preparing

- 174 -

• input data and parameters, and for interpretingresults

.

[A115.402] SOFTWARE SYSTEM : This approved and assembledsoftware package, including all related documentation,is physically ready for delivery.

[ A 1 15.4031 SOFTWARE SUMMARY ; A brief description of thesoftware system, giving its purpose, developer, andhistory. The description goes on the form included in

FIPS 30, "Software Summary."

- 175 -

GLOSSARY FOR A 1 1

6

BOX t A 1 1 6 . 1 ] PLAN OPERATION AND MAINTENANCE : Plan routineoperation and prepare a Maintenance Plan to cover allaspects of maintenance and modification of the newsoftware system.

BOX [A116.2] INSTALL SYSTEM : Load the software system intothe actual operating environment. Perform acceptancetesting, and train users in the operation of the sys-tem.

BOX LAI 16.33 USE SYSTEM : Operate the system that has beensuccessfully installed; exercise it at first through a

shakedown period, with representative workload, in theactual environment; after the " installation bugs” arefound, integrate the system into the operational en-vironment in production mode.

BOX [ A 1 16.4] EVALUATE SYSTEM : The user periodically evalu-ates operating software systems to search for problemsand to determine whether maintenance is satisfactory,whether modifications might improve the system, orwhether new developments in hardware or software tech-nology have made the current software system obsolete.

BOX [A116.5] MAINTAIN AND MODIFY : Maintain the system andmake modifications to meet changing operational re-quirements .

[A116.101] MAINTENANCE PLAN : Besides scheduling routinemaintenance, the Maintenance Plan includes a mechanismfor evaluating the system and reporting faults or prob-lems found after the software has been installed.

[ A 1 1 6 . 2C 3 3 INSTALLATION GUIDE : See C A 1 1 5 - -40 13: InstallationGuide and User's, Operations, and Program MaintenanceManuals

.

[ A 1 1 6 . 20 1 3 ACCEPTANCE TEST ANALYS IS REPORT ; This report do-cuments the installation of the system, giving theresults of the acceptance testing and noting any unusu-al occurrences. It reports what tests were run, whatinputs were used, and what outputs were produced, andit evaluates the general capabilities of the installedsoftware in the given operating environment.

[ A 1 1 6.2023 PROBLEM REPORT : A formal report of problems en-countered during installation of the software system.

- 176 -

[ A 1 1 6 . 20 3 1 OPERATIONAL SYSTEM AND DOCUMENTS : A successfullyinstalled software system, together with the documenta-tion necessary to use it.

[A116.3C2] SOFTWARE CHANGE NOTICE : This notice of systemchanges tells when the system was modified and notesrequired changes in existing documentation.

[A 1 1 6 . 302 ] OPERATION AND USAGE EXPERIENCE ; Information aboutthe actual operation of the system.

[A116.401] APPLICATION REPORT : The user's report that evalu-ates and describes his experiences with the softwaresystem. It tells how the software has affected hisbusiness and what training his personnel received. Italso describes adjustments or modifications, unusualapplications, or enhancements developed by the user.

[ A 1 1 6 . 40 2 ] MAINTENANCE REQUIREMENTS : Either routine or spe-cial problems with the software system that requiremaintenance or modification.

[A116.5C3] PROGRAM MAINTENANCE MANUAL : See [A115.501]: In-stallation Guide and User's, Operations, and ProgramMaintenance Manuals.

GLOSSARY FOR A12

BOX [ A 1 2 . 1 ] DETERMINE CONFORMANCE TO TECHNICAL ANDCONTRACTUAL SPECIFICATIONS : The contractor closely ex-amines his own product to make sure that it conforms totechnical and contractual specifications. He reviewsProblem Reports from the development team and decideswhether to propose software changes through a SoftwareChange Proposal, or to order the development team totry again to meet the contract specifications. Ap-proved documents go on to the next stage of internalreview. Noncompliant documents return to previousstages with redirections.

BOX [ A 1 2 . 2 ] PREPARE CHANGE PROPOSALS : Working with formalProblem Reports, the developer locates the cause of theproblem and prepares proposals for changing softwarerequirements or specifications.

BOX t A 1 2 . 3 ] MANAGE CONFIGURATIONS : After receiving a

Software Change Proposal, the configuration managernegotiates with the developer to come up with new con-tract specifications.

BOX [ A 1 2 . 4 ] REVIEW FOR CONFORMANCE TO ICAM STANDARDS : Atthis stage the contractor determines whether or not hissoftware documentation conforms to relevant ICAM stan-dards.

BOX [ A 1 2 . 5 ] DETERMINE ADEQUACY AND USABILITY OF DOCUMENTS :

As a final stage in the internal quality assurance cy-cle, the developer evaluates the documents for clarity,intelligibility, and modularity.

[A12.101] PROBLEM REPORTS : Formal reports of problemsdetected during development. These reports go both tothe ICAM PO (like other ICAM Software Documents) and tothe developer's personnel who propose changes to re-quirements or specifications.

t A 1 2 . 10 31 and [ A 1 2 . 40 2 ] APPROVED SOFTWARE DOCUMENTS : Thesedocuments have passed the internal review specified bythe boxes from which they emerge. The developerreleases them to the ICAM Program Office only afterthey have passed all inspections.

[A12.201 ] SOFTWARE CHANGE PROPOSAL : A proposal by the con-tractor for changes in requirements, specifications,documentation, or actual operating characteristics ofthe software system. It specifies both existing and

- 178 -

proposed versions of the requirements or specificationsin question

.

[A12.301] SOFTWARE CHANGE NOTICE : The Software Change Noticeofficially changes requirements, specifications, docu-mentation, or actual operating characteristics of thesoftware being developed or run. Its format is suit-able for it to be appended to existing contract specif-ications, and if produced during development ratherthan operation, it becomes part of pre-deliveryredirections .

[A12.5C1] ADDITIONAL QUALITY CONSIDERATIONS ; Factors— likereadability, attractiveness, organizational logic, andconsistency of presentat ion--that affect the quality ofICAM Software Documents.

[A12.3M1] ICAM PROGRAM OFFICE AND CONTRACTO R ; The ICAM con-tractor and the ICAM Program Officers in charge of con-figuration management.

- 179 -

GLOSSARY FOR A 1

3

BOX C A 1 3 . 1 ] REGISTER DOCUMENTS FOR DISTRIBUTION CON T ROL :

This is the developer's process for controlling docu-ments. It involves assigning document identificationcodes as well as dating, classifying, and logging inthe document. It also includes preparing an index toaccompany the software document when the developerreleases it to the ICAM Program Office.

BOX [ A 1 3 . 2 ] PRODUCE DELIVERABLE DOCUMENTS : Format, record,print, and bind ICAM Software Documents.

BOX [ A 1 3 . 3 1 INSPECT DOCUMENTS AND AUTHORIZE DELIVERY : Checkdocument copies for agreement with approved texts andformats before authorizing delivery to the ICAM ProgramOffice

.

[A13.101] BIBLIOGRAPHIC DATA SHEE T : A form (like DD 1 473 )

which lists author(s), title, sponsoring and producingagencies, general bibliographic information, and a con-trol number

.

[ A 1 3 . 10 2] REGISTERED DOCUMENTS : Documents which have beencategorized for distribution control.

[A 1 3 . 2C2 ]. PRODUCTION REDIRECTIONS : When the person who in-spects document copies finds differences between themand the approved original text, he returns them withproduction red i rec t ions— spec i f ic statements of changesneeded before delivery to the ICAM Program Office.

[ A 1 3 • 2 0 1 ] DOCUMENT COPIES : Master documents or production.copies to be inspected before delivery to the ICAM Pro-gram Office

.

- 180 -

GLOSSARY FOR A2

BOX [A2.1] REVIEW PROJECT DOCUMENTATION : The formal reviewperformed by the ICAM Program Office. Primary interestis in compliance with contractual requirements and withICAM standards and quality objectives. Compliant docu-ments are transmitted for dissemination, while noncom-pliant documents are returned to the contractors withredirection, in the form of required modifications andimprovements .

BOX [A2.2] EVALUATE SOFTWARE DOCUMENTATION SYSTEM : This is a

continuous process conducted by the ICAM Program Of-fice; it is especially important when a problem withthe Documentation System has been identified. As a

result of this evaluation, plans and schedules areprepared for documentation and dissemination of thesoftware documents . Possible output of this stage in-cludes the plans and schedules that go into ICAM pro-gram planning for major innovations and improvements inthe Documentation System.

BOX [A 2. 31 DEVELOP PROPOSED ICAM SOFTWARE DOCUMENTATI ONSTANDARDS : A problem in the Software Documentation Sys-tem may lead to the identification of specific needsfor standards. Technical specifications and applica-bility criteria for a proposed standard are developedand submitted for processing to the standard-making au-thority within ICAM.

[ A 2 . 10 2] N EW REQUI REMENTS : While monitoring a contract, theICAM Program Office may find it necessary to modifycontract specifications on a given project, or writenew requirements. This may result from a variety ofcircumstances, ranging from redefinition of ICAM needsto changes in policies.

[A2.2I1] PROBLEM IDENTIFICATION : When ICAM Program Officersfind documentation to be noncompliant , they return itto the contractors for modification and improvement.The office further examines noncompliant documents forpossible problem areas affecting the operation of theSoftware Documentation System. The officers then usethese identified problems to evaluate the overall Docu-mentation System.

[A2.201] INPUT TO ICAM PROGRAM PLANNING : Information fromthe evaluation of the Software Documentation Systemthat is pertinent to overall ICAM program planning.This kind of information is outside the scope of theSoftware Documentation System.

- 181 -

[A2.202] STANDARDS NEEDS : Identification of specific needsfor documentation standards; alternatively, a statementof inadequacy in existing standards.

- 182 -

GLOSSARY FOR A21

BOX [A 2 1.1] REVIEW FOR COMP LIANCE WITH TECHNIC AL ANDCONTRACTUAL SPEC IF ICA T IONS ; This function of the ICAMProgram Office is akin to the compliance review thatthe contractor performs prior to delivery. (See A12.1)In formally reviewing the software documents, the POmust determine whether these documents comply with thecontractual and technical requirements. If they do,then the review process continues. If they do not,then the documents go back to the contractor withredirections. In some cases, the PO may issue contractclarifications along with the post-delivery redirec-tions.

BOX [A21.2] REVIEW FOR CONFORMANCE TO ICAM STANDARDS : TheICAM Program Office formally ensures that delivered do-cuments conform to ICAM standards. This process isakin to the one performed by the contractor (SeeA 1 2 . 3 ) .

BOX [ A 2 1 . 3 ] DETERMINE USE AND DISTRIBUTION OF DOCUMEN TS : Ina process analogous to the one performed by the con-tractor (See A12.4), the ICAM PO evaluates the softwaredocumentation for clarity, traceability, portability,and modularity. After considering the potential audi-ence for the software, the Program Office determinesdissemination needs and provides dissemination guidancebefore releasing approved documents for dissemination.

[ A 2 1 . 10 3] and [A21.203 3 COMPLIANT DOCUMENTS : Documents thathave gone through the evaluation process and have beencertified compliant with technical, contractual, andstandards requirements.

- 183 -

GLOSSARY FOR A22

BOX [ A 2 2 . 1 ] EVALUATE SOFTWARE DOCUMENTATIO N STANDARDS ANDCOMPLIANCE : Analyze problems with the DocumentationSystem to see if they result from the standards them-selves, from questions of compliance, or from othermatters like administration or accounting.

BOX [A 22. 2] EVALUATE RESPONSIVENESS TO USER NEEDS : After re-viewing documentation standards, the ICAM Program Of-fice determines how well the Software DocumentationSystem responds to user needs.

BOX [ A22 . 3 ] EVALUATE DOCUMENTATION SYSTEM NEEDS : The reviewand evaluation of the Software Documentation Systemtakes place continually. However, if a problem occursin the operation of this documentation system, then theICAM Program Office thoroughly reviews and evaluatesthe management, operation, and processes of the system.

[A22.102] NON -STANDARDS PROBLEMS : Problems with the Documen-tation System that do not require changes in standards.

[ A 2 2 . 2 0 1 ] PROBLEM DEFINITION : Specifically identified prob-lems in the way the Documentation System responds tousers ' needs

.

[A22.301] NEW DOCUMENTATION SYSTEM REQUIREMENTS : Needed im-provements or additions to the existing DocumentationSystem

.

- 184 -

GLOSSARY FOR A23

BOX [ A 2 3 . 1 ] DEFINE AND EVALUATE ALTERNATI VE STAN DARDS : Usingidentified standards needs, the ICAM Program Officeevaluates existing ICAM standards for technical defi-ciencies, examines alternative ways to correct the par-ticular standards problem, and selects one approach asthe best.

BOX [A 2 3. 2] DEVELOP TECHNICAL SPECIFICATION S FOR STA NDARDS :

ICAM standards developers either write technicalspecifications for new standards or revise the techni-cal specifications of existing standards to removeidentified deficiencies.

BOX [ A2 3 . 3 ] DEVELOP APPLICABILITY CRITERIA : Develop criteriafor applying the new technical standards. Add thesecriteria to the technical specifications to produceproposed ICAM Software Documentation Standards.

[ A 2 3 . 1 C 2 ] EXISTING ICAM STANDARDS : Standards that alreadyexist in the ICAM environment and that apply tosoftware documentation. [See also definition of Stan-dards under A-0.0C2, ICAM Program Requirements].

[ A 2 3 . 10 1 ] SELECTED APPROACH : The chosen approach fordeveloping new standards to meet existing standardsneeds .

[ A 2 3 . 20 1 ] TECHNICAL SPECIFICATIO NS FOR PROPOSED STANDARD S

:

Technical specifications that modify existing standardsor constitute new standards.

- 185 -

GLOSSARY FOR A3

BOX [A3. 1 ] PREPARE DISSEMINATION RECORDS ; Preparing auxili-ary documents to control dissemination of approved mas-ter documents

.

BOX [A3. 2] MANAGE DISSEMINATIO N TASKS : Determine dissemina-tion requirements, allocate resources, keep track of

orders and inventory, and authorize dissemination ofservices .

BOX [A3. 3] PROVIDE INFORMATION SERVICES : Make available suchservices as an online document retrieval service, or an

information retrieval service.

BOX [A3. 4] DISTRIBUT E DOCUMENTS ; Included are the physicalstorage and distribution of documents.

[A3. 101] DISCREPANCIES : Differences between the intended andactual documents, including missing parts and internalinconsistencies

.

[A3. 102] PROCESSED DOCUMENTS : Master documents together withtheir indexes, catalogs, abstracts, and other secondarydocuments

.

[A3. 212] REQUESTS FOR DOCUMENT REPRODUCTIONS ; Requests formore copies of ICAM Software Documents to replenish ex-isting inventories.

[A3. 213] ORDER AND INVENTORY STATISTIC S : Statistics calcu-lated from information about existing inventory and in-

coming orders .

[A3. 201] BILL OF MATERIALS AND COS T EVALU A TIO N : A breakdownof the physical elements comprising each document. For

a report it would include paper size and type (i.e.,white bond, red construction, glossy print, etc.). Cou-pled with an inventory, this breakdown makes it possi-ble to evaluate and predict costs, to determine whensupplies should be ordered, and to estimate the associ-ated delays.

[A3. 202] AUTHORIZATI ON TO PROVID E SERV ICES : Authority to runan information retrieval service and to distribute do-cuments .

[A3. 312] INFORMAT ION ABOUT ORDERS AND INVE N TORY : Raw data on

orders and inventory that can be processed into usablestatistics about the Documentation System.

- 186 -

CA 3. 301] DOCUMENT INFORMATION RETRIEVAL SERVICE : A servicethat provides abstracts, indexes and other informationenabling users to get access to ICAM Software Documentsor products.

[A3. 302] PUBLICITY : Catalogs, announcements, newsletters,and other documents that inform potential users ofavailable ICAM software and documents.

[A3- 3031 MANAGEMENT INFORMATION : Management-oriented chartsand reports that summarize a particular operation orfunct ion--e . g . , the number of documents in productionor storage. Examples of this kind of report are sum-maries, statistical reports, productivity reports, costevaluations, and user and document profiles. This typeof information is required for the effective evaluationand planning of documentation activities.

-18 7-

-

GLOSSARY FOR A3

1

BOX [ A 3 1 . 1 ] INSPECT AND LOG IN DOCUMENTS : Check the masterdocument for compliance with ICAM documentation stan-dards and assign it an accession number.

BOX [ A 3 1 . 2 ] DESCRIBE DOCUMENTS : Index the documents by sub-ject code and key words.

BOX [A3 1.31 UPDATE CATALOGS OF EXISTING SOFTWARE DOCUMENT S

:

Use information about a new software document to updatea catalog of existing software documents.

[ A 3 1 . 10 2] LOGGED -IN MASTER DOCUMENTS : Master documents whichhave acquired a control number and are ready fordescriptive indexing.

[ A 3 1 .201 ] PROCESSED DOCUMENTS : Primary and secondary docu-ments for ICAM software.

[ A 3 1 . 31 1 ] DOCUMENT DESCRIPT ION WORK SHEET ; The secondary do-cuments which describe and control ICAM Software Docu-ments .

[A31.301] REVISED CATALOGS : Catalogs which have been revisedto include new ICAM Software Documents.

- 188 -

GLOSSARY FOR A32

BOX [A32.1] DETERMINE DISSEMINATION NEEDS AND COSTS ; Usinginformation about composition and usage of documents,produce a bill of materials and a cost evaluation fordissemination

.

BOX [A 32. 2] AUTHORIZE DISSEMINAT ION TAS KS : Tell the dissemi-nation personnel when and how to provide informationservices and documents.

- 189 -

GLOSSARY FOR A33

BOX [ A 3 3 . 1 ] MAINTA IN MANAG E MENT INFOR M ATION : Keep order andinventory statistics, information about the documenta-tion archive, and information about special interestusers. Information on new software documents will beused to update existing management information.

BOX [ A 3 3 . 2 ] PROVIDE INF ORMATION RETRIEVAL SERVICES : Storeand give out information about ICAM Software Documents,including indexes, abstracts, catalogs, and general bi-bliographic information.

BOX [ A 3 3 . 3 3 PUBLICIZE DOCUMENTS : Prepare announcements, ca-talogs, and newsletters to inform potential users aboutavailable ICAM Software Documents.

[A33.2I1] RELE VANT INFORMATION ; Management information thatmay improve information retrieval services.

[A33.3C1] SPECIAL INTEREST INFORMATION : Management informa-tion about present and prospective users of ICAMSoftware Products and Documents.

- 190 -

GLOSSARY FOR A34

BOX [ A 3 4 . 1 ] MAINTAIN DOCUMENTATION ARCHIVE : Operate a li-brary of master documents and production copies of allICAM software. Keep track of inventories of each docu-ment, and release documents when needed for dissemina-tion.

BOX [ A 3 4 . 2 ] PROCESS ORDERS : Handle incoming orders from ICAMusers. Record orders, update order and inventory in-formation, and release orders to be filled.

BOX [A 34. 3] SEND DOCUMENTS : Fill all processed orders withcopies of documents from the documentation archive.

[ A 3 4 . 10 1 ] DOCUMENTATION ARCHIVE : The library of master docu-ments and production copies of all ICAM software.

[ A 3 4 . 10 2] UPDATED ORDER AND INVENTORY INFORMAT ION : These up-dates of order and inventory statistics take into ac-count any discrepancies between incoming statistics andexisting inventory.

[ A 3 4 . 10 3 1 COPIES OF DOCUMENTS : Copies of ICAM Software Docu-ments to be distributed to customers.

NBS-114A (REV. 9-78)

U.S. DEPT. OF COMM.

BIBLIOGRAPHIC DATASHEET

1. PUBLICATION OR REPORT NO.

NBSIR 79 - 1940 (R)

4. TITLE AND SUBTITLE

ICAM Software Documentation Standards

7. AUTHOR(S)

Center for Programming Science & Technology, Institute forComputer Sciences and Technology

ill

'mmiiuiiiiiiiiii iii

5. Publication Date

8. Performing Organ. Report No.

9. PERFORMING ORGANIZATION NAME AND ADDRESS

NATIONAL BUREAU OF STANDARDSDEPARTMENT OF COMMERCEWASHINGTON, DC 20234

11. Contract/Grant No.

MIPR FY1 457 -77-02054

12. SPONSORING ORGANIZATION NAME AND COMPLETE ADDRESS (Street, City, state, zip)

Air Force Materials LaboratoryWright - Patterson Air Force BaseOhio 45433

13. Type of Report & Period Covered

NBSIR 10/77 - 10/79

15. SUPPLEMENTARY NOTES

I IDocument describes a computer program; SF-185, FIPS Software Summary, is attached.

16. ABSTRACT (A 200-word or leas factual summary of most significant Information. If document includes a significant bibliography or

literature survey, mention it here.)

The ICAM Program Office requires all contractors who develop ICAM software

to comply with the following standards governing style and content of ICAM Soft-

ware Documents. The Style Guide, which covers writing and programming style,

applies to all documentation, and individual Content Guides function within the

overall framework defined by the IDEF Functional Model and its glossary.

17. KEY WORDS (six to twelve entries; alphabetical order; capitalize only the first letter of the first key word unless a proper name;separated by semicolons)

Computer-aided manufacturing; computer standards; programming style; software

documentation; structured analysis.

18. AVAILABILITY Unlimited

1X1 For Official Distribution. Do Not Release to NTIS

I 1 Order From Sup. of Doc., U.S. Government Printing Office, Washington, DC20402, SD Stock No. SN003-003-

I |Order From National Technical Information Service (NTIS), Springfield,

VA. 22161

19. SECURITY CLASS(THIS REPORT)

UNCLASSIFIED

20. SECURITY CLASS(THIS PAGE)

UNCLASSIFIED

21. NO. OFPRINTED PAGES

22. Price

USCOMM'DC