A111D3 DfiTEMT

NATL INST OF STANDARDS i TECH R.i.C.

A11 103089249

Symposium tor Docume/Documentation of co QC100 .U57 NO.500-15. 1977 C.I NBS-PUB-C CE & TECHNOLOGY:

DOCUMENTATION OF

COMPUTER PROGRAMS

AND AUTOMATED

DATA SYSTEMS

500-15

7

NBS Special Publication 500-15

U.S. DEPARTMENT OF COMMERCE

National Bureau of Standards
NATIONAL BUREAU OF STANDARDS

The National Bureau of Standards^ was established by an act of Congress March 3, 1901. The Bureau's overall goal is to strengthen and advance the Nation's science and technology and facilitate their effective application for public benefit. To this end, the Bureau conducts research and provides: (1) a basis for the Nation's physical measurement system, (2) scientific and

technological services for industry and government, (3) a technical basis for equity in trade, and (4) technical services to pro- mote public safety. The Bureau consists of the Institute for Basic Standards, the Institute for Materials Research, the Institute for Applied Technology, the Institute for Computer Sciences and Technology, the Office for Information Programs, and the

Office of Experimental Technology Incentives Program.

THE INSTITUTE FOR BASIC STANDARDS provides the central basis within the United States of a complete and consist- ent system of physical measurement; coordinates that system with measurement systems of other nations; and furnishes essential services leading to accurate and uniform physical measurements throughout the Nation's scientific community, industry,

and commerce. The Institute consists of the Office of Measurement Services, and the following center and divisions: Applied Mathematics — Electricity — Mechanics — Heat — Optical Physics — Center for Radiation Research — Laboratory Astrophysics^ — Cryogenics'' — Electromagnetics'' — Time and Frequency".

THE INSTITUTE FOR MATERIALS RESEARCH conducts materials research leading to iniproved methods of measurement, standards, and data on the properties of well-characterized materials needed by industry, commerce, educational insti- tutions, and Government; provides advisory and research services to other Government agencies; and develops, produces, and < distributes standard reference materials. The Institute consists of the Office of Standard Reference Materials, the Office of Air

[ and Water Measurement, and the following divisions:

Analytical Chemistry — Polymers — Metallurgy — Inorganic Materials — Reactor Radiation — Physical Chemistry.

THE INSTITUTE FOR APPLIED TECHNOLOGY provides technical services developing and promoting the use of avail- able technology; cooperates with public and private organizations in developing technological standards, codes, and test methods; and provides technical advice services, and information to Government agencies and tlie public. The Institute consists of

the following divisions and centers: Standards Application and Analysis — Electronic Technology — Center for Consumer Product Technology: Product Systems Analysis; Product Engineering — Center for Building Technology: Structures, Materials, and Safety; Building

Environment; Technical Evaluation and Application — Center for Fire Research: Fire Science; Fire Safety Engineering.

THE INSTITUTE FOR COMPUTER SCIENCES AND TECHNOLOGY conducts research and provides technical services designed to aid Government agencies in improving cost effectiveness in the conduct of their programs through the selection, acquisition, and effective utilization of automatic data processing equipment; and serves as the principal focus wthin the executive branch for the development of Federal standards for automatic data processing equipment, techniques, and computer

languages. The Institute consist of the following divisions: Computer Services — Systems and Software — Computer Systems Engineering — Information Technology.

THE OFFICE OF EXPERIMENTAL TECHNOLOGY INCENTIVES PROGRAM seeks to affect public policy and process

to facilitate technological change in the private sector by examining and experimenting with Government policies and practices in order to identify and remove Government-related barriers and to correct inherent market imperfections that impede

the innovation process. THE OFFICE FOR INFORMATION PROGRAMS promotes optimum dissemination and accessibility of scientific information generated within NBS; promotes the development of the National Standard Reference Data System and a system of in- formation analysis centers dealing with the broader aspects of the National Measurement System; provides appropriate services

to ensure that the NBS staff has optimum accessibility to the scientific information of the world. The Office consists of the following organizational units:

Office of Standard Reference Data — Office of Information Activities — Office of Technical Publications — Library —

Office of International Standards — Office of International Relations.

1 Headquarters and Laboratories at Gaithersburg, Maryland, unless otherwise noted; mailing address Washington, D.C. 20234.

" Located at Boulder, Colorado 80302.
NATIONAI. BURBAU

OF BTAKDARDS

LIBRAJKY COMPUTER SCIENCE & TECHNOLOGY: nov 2 4 1980

Documentation of Computer Programs and

Automated Data Systems '

Proceedings of a Symposium

Held at the National Bureau of Standards,

Gaithersburg, MD, October 12, 1976

Edited by:

Mitchell A. Krasny

National Technical Information Services

Springfield, VA 22161

Sponsored by

Federal Information Processing Standards Task Group 14 (Documentation for Information Processing Systems) National Bureau of Standards Washington, D.C. 20234

In conjunction with the ADP Management Center

U.S. Civil Service Commission

Washington, D.C. 20415

U.S. DEPARTMENT OF COMMERCE, Juanita M. Kreps, Secretary

Dr. Sidney Harman, Under Secretary

Jordan J. Baruch, Assistant Secretary for Science and Technology

NATIONAL BUREAU OF STANDARDS, Ernest Ambler, Acting Director

Issued July 1977

flQ.S'OO'i:

mo
Library of Congress Cataloging in Publication Data Main entry under title: Documentation of computer programs and automated data systems. (Computer science & technology) (NBS special publication ; 500-15) Siipt.ofDocs.no.: C13.10:500-15.

I. Electronic data processing documentation—Congresses. I. Krasny,

Mitchell A. II. Federal Information Processing Standards Task Group

14 on Documentation for Information Processing Systems. III. United

States. ADP Management Training Center, Washington, D.C. IV.

Series. V. Series: United States. National Bureau of Standards.

Special Publication ; 500-15. QC100.U57 no. 500-15 [QA76.9.D6] 602Ms 77-608169 [001.6'425]

National Bureau of Standards Special Publication 500-15

Nat. Bur. Stand. (U.S.), Spec. Publ. 500-15, 66 pages (July 1977) CODEN: XNBSAV

For sale by the Superintendent of Documents, U.S. Government Printing Office, Washington, D.C. 20402

Price $2.10—Stock No. 003-003-01814-7
ABSTRACT

This symposium was organized to introduce the Government ADP community to

the concepts of when and how to apply the government-wide guidelines of FTPS

PUB 38 "Guidelines for Documentation of Computer Programs and Automated Data

Systems" - in developing both agency standards and operational

documentation. The proceedings contain all of the papers presented in the

plenary session, and the papers plus summaries of question and answer

sessions presented in three parallel sessions for management, operations,

and staff attendees.

KEY WORDS

Automated data systems; computer programs; documentation, documentation

content guidelines; FIPS guidelines; software; symposium proceedings.

iii
PREFACE

The planning, design, development, and implementation of computer programs

and automated data systems (software) represent a considerable investment of

human and automated resources. To maximize the return on this investment,

and to provide for cost-effective operation, revision, and maintenance,

sufficient documentation is needed in each stage of the software development

life cycle. FIPS PUB 38 was prepared to provide Government-wide guidelines

in response to that need. In order to introduce the government ADP

community to the concepts of FIPS PUB 38, FIPS Task Group 14 (Documentation

for Information Processing Standards) organized a symposium to provide

attendees with a fuller understanding of when and how to apply these

government-wide guidelines in developing agency standards or operational

documentation. That symposium is documented in these proceedings.

Because the publication process is already longer than it should have been,

the authors have not had an opportunity to review the results of my editing.

I accept responsibility for any change in meaning which this process may

have inadvertently introduced. My editing was limited to:

Style - I imposed a degree of consistency to different references to the same subject (for example, four different ways of writing "FIPS PUB 38";

Clarity - I tried to untangle some grammatical constructions which, while

acceptable in an oral presentation, are cumbersome or confusing on paper;

Space - in a few cases, I shortened sentences here and there to keep a paper

from ending with only two or three lines on the past page.

One of the purposes FIPS TG 14 had in mind for this symposium was to open

channels for feedback on FIPS PUB 38 from the attendees. Only time can tell

how well that purpose was achieved. Meanwhile, FIPS TG 14 is developing

guidelines for other document types. Included in the list, as of this

writing, are: Project Request, Project Notebook, Project Development Plan,

Pos t- Ins t a 1 1 a t i on Evaluation Report, System Development Ac t iv i ty /Tas

Report, Feasibility Analysis Document, and Cost/Benefit Analysis Document,

Readers who are interested in working on any of these projects, or who can suggest additional ones, may contact any TG-14 member, or the office of the

Associate Director (of NBS) for ADP Standards, (301) 921-3157.

On behalf of FIPS TG 14, I wish to express appreciation to the speakers and

panelists, who contributed so much of their time and effort to this

symposium; to the National Bureau of Standards, for administrative and

logistical support, which made the symposium run smoothly; and to the Civil

Service Commission, which was extremely helpful in the final planning for

and announcing of this symposium. Mark Silverman, Roy Young, and I had all

the fun of putting it together, while all these others had all the work.

Finally, this symposium could not have been successful without the

wholehearted support of the nearly 300 attendees, without whom the whole

thing would have been pointless. We thank you very much.

On a final, personal note, I wish to thank all the secretaries who typed

their bosses' speeches, and got them to me by the deadline. By the time I had edited the first few, I realized that they'd all have to be retyped. My own secretary, Mrs. Karen V, Warraus, has done an outstanding job, and has

helped me tremendously in this undertaking.

March 24, 1977 Mitchell A. Krasny, Editor

Springfield, Va 22161 National Technical Information Service

iv
TABLE OF CONTENTS

ABSTRACT & KEYWORDS

PREFACE

TABLE OF CONTENTS

INTRODUCTION

Mark Silverman

WELCOME ADDRESS

M. Zane Thornton

WHY DOCUMENT?

Theodore D. Puckorius

THE PHILOSOPHY OF FIPS PUB 38 - AN INTRODUCTION

Jame s Gillespie

LIFE CYCLE CONCEPTS AND DOCUMENT TYPES

Roy A. Young

FLEXIBILITY PROVISIONS AND DOCUMENT TYPE SELECTION

Robert R, Hegland

CONTENT GUIDELINES

Thomas M, Kurihara

DESCRIPTION OF AFTERNOON SESSIONS

Mark Silverman

SESSION A

USDA APPLICATION MANAGEMENT

Robert V. Head

DOCUMENTATION STANDARDS - A MANAGEMENT VIEW

Eugene B. Smith

KEY ELEMENTS IN THE ADP SYSTEM DEVELOPMENT PROCESS AT HUD

Dr. Marvin Goer

SYNOPSIS OF QUESTIONS AND ANSWERS FROM PARALLEL SESSION A

Greg Loss and Tom Kurihara

SESSION B INTRODUCTION: ADP SYSTEMS, OPERATIONS, AND PROGRAMMER PERSONNEL

Thomas Giammo

PROBLEMS IN USING THE DOCUMENTATION GUIDELINE

Robert R. Hegland

SYNOPSIS OF QUESTIONS AND ANSWERS FROM PARALLEL SESSION B Robert A. Mattes and Kenneth Rodey

SESSION C INTRODUCTION: "STANDARDS, TRAINING, POLICY AND AUDIT PERSONNEL"

Harris G. Reiche

FIPS PUB 38 - IMPLEMENTATION PHILOSOPHY IN HEW

Joseph J. Strnad

THE ROLE OF THE AUDITORS IN THE DEVELOPMENT & EVALUATION OF

AUTOMATED SYSTEMS

Phillip L. Morrison

SYNOPSIS OF QUESTIONS AND ANSWERS FROM PARALLEL SESSION C Fred J, Cole and Edie Lasner

FIPS TASK GROUP 14 MEMBERSHIP & SYMPOSIUM PLANNING COMMITTEE

BIBLIOGRAPHIC DATA SHEET

V

INTRODUCTION

Mark Silverman, Sympos ium Cha

s i s t an t Survey

1 Stop

22092

irman

Technical Staff As

U. S. Geological

National Center, Mai

Reston, Virginia

801

Welcome to the Symposium for Documentation of Computer Programs and

Automated Data Systems, which is being held to afford attendees a better

understanding of FIPS PUB 38. FIPS Task Group 14 developed FTPS PUB 38 as a set of guidelines for Government-wide use to meet the need for adequate and

consistent documentation during the development stage of a software system's

life cycle

.

The life cycle of a software system includes the stages of planning, design,

development, implementation, and maintenance. Each of these stages may

require a substantial investment in time and other resources.

This symposium should help attendees apply the guidelines in FIPS PUB 38 to

reduce costs significantly. We hope you will find these guidelines helpful

both in the development of agency standards for software documentation and

in documenting computer programs and automated data systems.

And now, I am pleased to present Mr. M. Zane Thornton, the Deputy Director

of the Institute for Computer Sciences and Technology, the National Bureau

of Standards. Mr. Thornton will provide some background on the FIPS program

and introduce our distinguished Keynote speaker.
WELCOME ADDRESS

M, Zane Thornton

Deputy Director

Institute for Computer Sciences and Technology

National Bureau of Standards

Washington, D. C. 20234

Good morning, Ladies and Gentlemen, I am pleased to welcome you to the

National Bureau of Standards and this Symposium on the Documentation of

Computer Programs and Automated Data Systems. Before I introduce our keynote speaker, let me briefly review the NBS ADP Standards program and

the Federal Information Processing Standards (or FIPS) activities which

produced the documentation guidelines which are the subject of today's

me e t ing . Since enactment of Public Law 89-306 (Brooks Act), the National Bureau of

Standards has had a leadership role in the management of activities within

the Federal Government relating to the development and maintenance of

uniform Federal automatic data processing standards. The continuing

objectives of the NBS ADP Standards Program are to facilitate the

interchange and sharing of data, programs, and equipment by Federal

agencies; to improve performance and quality of ADP products and services

developed by or acquired by Federal agencies; and to make Government and

industry aware of the need for standards to achieve compatibility and

enhance the effective utilization of ADP products and services in the

preparation and delivery of public services.

The Federal Information Processing Standards program sets mandatory

standards for the Federal ADP-communi ty . In carrying out this program, NBS

has maintained close cooperation with the voluntary standards activities of

the American National Standards Institute (ANSI) and the International

Organization for Standardization (ISO), NBS, in its standards management

role, is responsible for assuring Federal participation in the development

of ANSI and ISO voluntary standards, for considering them for adoption as Federal standards in those cases where they meet the requirements of the

Federal Government, or for initiating independent development actions in cases where ANSI and ISO efforts do not exist, or are too slow.

The NBS FIPS program identifies those areas in which ADP standards are needed, pursues their development, and promulgates the completed standards

through Federal Information Processing Standards Publication (FIPS PUBS).

Presently there are fourteen active FIPS task groups with over 350

professional participants from Government and industry, addressing such areas as programming languages, data codes, security and privacy, network

protocols, and documentation. To date, 44 standards, guidelines, and

information documents have been developed and published by NBS in the FIPS

PUB series. The current standards effort addresses four major areas: (1)

standards that provide for the effective interchange and sharing of data,

programs, and equipment, (2) standards to increase the performance and assure quality control of ADP products and services; (3) standards that

facilitate the transfer and use of computer technology through effective

man-machine interfaces; and (4) standards to provide for the safety and

security of personnel, equipment, and data. Priorities are given those

standardization development efforts which have the most need and highest

potential benefit.

In June 1974, in a letter from the Director of NBS to the Director of the

General Government Division of the General Accounting Office, Documentation

was cited as one of the highest priority subjects in the Federal ADP

Standards Program. In October 1974, the Comptroller General of the U.S. in

a report to Congress entitled "Improvement Needed in Documenting Federal

Computer Systems" affirmed that "Government standards are not available to

2
assist Federal managers in deciding what type of documentation to prepare,

how much to prepare, and when and how to prepare it." The report noted that

"although good documentation does not insure successful computer op^erations,

inadequate documentation can

o increase the cost of Federal operations,

o weaken management control of ADP systems,

o contribute to loss of funds and assets, and

o limit the potential for sharing programs."

FIPS Task Group 14, "Documentation for Information Processing Systems", was established in March 1973, and charged with developing standards and

guidelines for the documentation of individual computer programs and

automated data systems. This task group is composed of representatives of more than twenty Federal agencies. FIPS PUB 38 is one of the products of

this group. Using available guidelines from various Federal, commercial,

and academic organizations as points of departure, the group selected the

best features of the best of these, and made them generally applicable to

Federal computer installations. FIPS PUB 38, which you have as part of your

registration packet, has been extensively reviewed, revised and coordinated

among the Federal and non-Federal ADP community.

These guidelines for Documentation of Computer Programs and Automated Data

Systems have been prepared in response to the need for documentation to

support the effective management of ADP resources, and to facilitate the

interchange of information about computer software. The objectives are to:

o Provide managers with technical documents to review at

significant development milestones,

o Record technical information to allow later use and

modification of software,

o Facilitate understanding among managers, developers,

programmers, and users of software,

o Increase the potential for transferability and sharing

of so f twar e , and

o Provide a basis for auditability of software.

Your study of these guidelines today should help achieve these goals.

At this point, I'd like to thank the ADP Management Center of the U.S. Civil

Service Commission, for jointly sponsoring this symposium with us.

Now it gives me great pleasure to introduce our featured speaker, Mr.

Theodore D. Puckorius.

Theodore D. Puckorius was appointed Commissioner of the General Services

Administration's Automated Data and Telecommunications Service (ADTS) on May

19, 1975. As ADTS Commissioner, he heads an organization which is

responsible for centralized management of general purpose data processing

and support services for all Federal agencies, as well as management and

operations of the civilian government's telecommunications system. ADTS'

operations include overall procurement responsibility for nearly $800

million worth of ADP hardware, software, services, and maintenance annually;

coordination, consolidation, and collocation of Federal requirements to

allow maximum utilization and sharing of government com^)uter resources;

operation of three Federal Data Processing Centers which provide a full
range of data processing services for individual agencies; an inter-active

timesharing computer system which permits remote access service nationwide;

and a comprehensive, multi-million dollar communications network which

serves Federal agencies across the nation through some one million phones,

over 10 million miles of circuitry, and thousands of data transmission

devices

Prior to his appointment as ADTS Commissioner, he was Vice President and

Managing Officer of the Government Services Division for Lester B. Knight

and Associates, Inc. in Chicago, Illinois, and Washington, D. C. Lester B. Knight is a Chicago-based firm specializing in management consulting and

architectural/ engineering services.

From 1965 until 1971, he served in key management positions with Booz, Allen

and Hamilton, Inc., a Chicago consulting firm. Previously, he held

increasingly responsible positions with North American Aviation in Columbus,

Ohio; AVCO Electronics and Ordnance Division in Cincinnati, Ohio; Hertz

Corporation in Chicago, Illinois; and the Pillsbury Company in Minneapolis,

Minne sota

Mr. Puckorius was born in Chicago on April 7, 1930. He attended DePaul

University and received a Bachelor of Science degree with honors from the

University of Illinois. He has done graduate work in financial management

and production management at the University of Illinois and Ohio State

University. He is a veteran of the United States Air Force.

Mr. Puckorius will discuss why we have documentation standards and

guidelines. His talk is titled: "Why Document?"
WHY DOCUMENT?

Theodore D. Puckorius

Commissioner, Automated Data and Telecommunications Service

General Services Administration

18th & F Streets, NW, Room 3240

Washington, D. C. 20405

Of increasing concern in the past few years has been technology transfer

which implies the communication of some technological advancement from the

innovators to those who need the information. Technological developments

follow one another at a furious pace. So rapid is the progress that the

pioneers in one area run the risk of finding that what they are perfecting

at great expense and great effort is also being perfected in another

location, likewise with great expense and great effort. One of the

particular areas of technology transfer which has been of great interest is

that of computer software, and development of such software represents a significant portion of the Federal ADP Budget.

Fiscal Year 1975 Federal ADP Inventory shows the total annual cost for ADP

in the government to be approximately $3.1 billion. If you take from this

figure the $850 million spent for hardware purchase and rental, supplies and

site preparation, you will see that a total of $2.25 billion was spent on software and related personnel costs alone. That is approximately three

times the amount of all other ADP related costs combined. As FTPS PUB 38

states in the introduction: " To maximize the return on this investmpntj and

to provide for cost-effective operation. revision and maintenance,

sufficient documentation is needed at each stage of the software development

life cycle".

Documentation is essential to the effective development, implementation,

modification, operation, and utilization of any system. Yet this is a notoriously weak area in the ADP industry —and one in which there are few

industry-wide standards or guidelines. Books on programming and

documentation techniques have been published almost since the first program

written in issachine language; and large organizations and institutions have

established internal standardization requirements'. Nevertheless, no one single cohesive agreement on documentation has been reached or accepted for

widespread usage. Likewise, funding constraints, tight scheduling and

general programmer distaste for writing —have generally relegated program

documentation to the lowest priority. As a result, the GAO Study on Automated Decision Making indicates there is much room for improvement.

Existing standards are not being complied with.

Documentation could be and is used by a variety of ADP-industry people

during the initiation, development and operation phases of the software life

cycle.

systems analysts require documentation in planning new systems

programmers need documentation when writing instructions

to implement the analysts' plans

. management needs some type of documentation when monitoring

and controlling system development and operations.

auditors need documentation in evaluating system reliability

and in advising management of possible system shortcomings.

The documentation used by these people can be categorized into four major

areas of application: 1) user, 2) system, 3) program, and 4) operations.

5
There are many levels of users of software systems with differing

information needs —from top level management, through operating management,

to the equipment operator. For a software system to be used productively,

instructions and aids to understanding for all levels of intended users must

be provided by system documentation.

How is this rather limited documentation emp loyed by the user?

The input-layout and completion instructions enable the user to comp le te

specified documents for input to the system. The output report definitions

and explanations gives the user the basis for understanding and interpreting

the output. Should a problem develop with the input, the error correction

procedures provide the user the means for re-inputting corrections.

In many data processing applications there is no user documentation at all.

Input documents are considered to be self-explanatory —as are the reports

generated by the system. To correct errors —either an error code is

issued —or it is left up to the user to figure out his own mistake.

Why Document?

Why, indeed!! Most data processing systems cost substantial amounts of

money, manpower, equipment, and time to develop. They were developed for

utilization by user departments. But, can the user make best use of the

system's resources and potential with scant —or worse yet--no documentation?

For effective utilization of any system, the user must understand the

purpose of the system, how the system works —functionally—and what the

system's capabilities are. The user must understand how the capabilities

can be most effectively utilized.

System documentation in most data processing installations ranks as the

lowest priority in the already low priority that documentation holds. It is

therefore usually non-existent.

System documentation should exist to specify for the analysts and

programmers-- the requirement s —the operat ing , environment —the design

characteristics -- and program specifications for a system.

Documentation should exist, but, all too often, much unnecessary work and

wasted time is encountered due to the absence of documented definitions or detailed specifications. Many changes must be made due to poor

communication and poor documentation of the users' needs.

Essential to the development of an efficient and effective system are concrete and well defined job objectives and specifications. The system

analyst (or system designer) cannot effectively accomplish his end, and

supply the programming staff with a workable detail design if the work has

had to come from inadequately defined objectives.

The problems arising from a lack of (or poor) system documentation magnify

themselves as the system development progresses. Each step in the growth of

a system is dependent upon the accuracy and effectiveness of the work and

documentation of the preceding steps.

During po s t- imp 1 emen t a t i on review, the system documentation is the only

valid means of comparison between the use-specifications and the end

results. Without it, one must rely upon the "best recollections" of

individuals involved. Hopefully, those individuals are still available to

query. When changes, modifications, or maintenance becomes necessary, the

system analysts (designers) and/or programmers must rely upon their

experience with the system (if any) or piece together program documentation

(if any), unless system documentation is available. This makes the

6
analyst/programmers' jobs not only difficult, but expensive —as it requires

substantially more time and work on their part to understand the current

system--in order to apply changes. Systems documentation is important

because it saves both time and money. Similarly, the programmer cannot

design and program efficiently to meet the user needs without accurate and

detailed specifications.

Equally important to both the maintenance and the operations staff is the

programmer's documentation. Program documentation provides the maintenance

programmers with the knowledge essential for effective debugging and

implementation of enhancements and modifications. Often the person

maintaining a program is not the author. Complete program documentation is

less costly in man hours than having maintenance programmers wade through

source codes to obtain the understanding of the program they need.

Documentation provides the operations personnel with the specifications and

requirements essential to planning har dwar e / s o f twar e needs.

Operations personnel can also lend valuable expertise in terms of

hard war e / s o f twar e utilization, scheduling requirements, and input/ output

handling in the system design stage of a process. Cooperation between

programming and operations can prove a valuable asset to any system

deve 1 opmen t

.

Why Document?

Documentation provides the means for the

utilization of the system by the user. greatest and most efficient

Documentation provides the

integration of the system. means for careful, well-planned design and

Documentation provides the maintenance programmers with the knowledge

essential for effective debugging and implementation of enhancements and

modifications.

Documentation provides the operations personnel with the specifications and

requirements essential to planning har dware / s o f twar e needs and scheduling

computer utilization.

Further, documentation provides for successful and cost effective sharing.

The recently established Software Exchange program by ADTS provides for the

sharing of computer programs developed by one organization for use by

another organization on a similar task. Documentation of programs and

systems must be adequate to enable the secondary user to understand the

program capabilities, peculiarities, and limits in order to determine

whether the program meets the needs stipulated. Secondary users also need

good documentation to understand how to run the program and to make any

necessary modifications.

In ad d i t pro j ec t requ i r em canvasse

need for

the Stat

so f twar

e

better d technica

include:

ion to the Software Exchange program, GSA has recently established a to obtain documentation Software for government-wide use under a ents-type contract. As a follow-on to a 1974 GAO Study, wherein GAO

d 70-different ADP installations and concluded that there exists a better documentation in the Federal government; and in keeping with

ed objectives of FIPS PUB 38; GSA is taking an active role in

management. Through this current procurement, we plan to promote

ocumentation in the Federal government and encourage the use of a lly valid automated documentation system. The expected benefits

more emphasis on good documentation, with the result that

Federal ADP Managers will become cognizant of this need.

7
In the long term, this emphasis should

ment by industry of more efficient and

for government use

result in developfeconomical software

. better documentation of government systems which will aid

in application program development and program maintenance

. achievement of volume discounts through centralized bulk

procurement and elimination of procurement costs on an agency-by-agency basis.

Why Document?

Because it is essential to the effective development, implementation,

modification, operation and utilization of any system.

8
THE PHILOSOPHY OF FIPS PUB 38 - AN INTRODUCTION

James Gillespie

Chief of Naval Operations (OP-914D)

Department of the Navy

Washington, D. C. 20350

'I

j My part in this program is very simple, and very pleasurable. First, I wish

! to express the appreciation of FIPS Task Group 14 to Mr. Thornton and Mr.

Puckorius for taking the time to participate in this tyBposiuni.

Second, I want to introduce the next three speakers, who will describe the

different aspects of the philosophy behind FIPS PUB 38. Roy Young will

describe the life cycle concept and the document types which occur at each

stage in that life cycle. Bob Hegland will describe the flexibility that

f each agency has, both in developing in-house standards or guidelines, and

when selecting document types in any given application. Finally, Tom

Kurihara will provide a brief description of the content guidelines for each

of the ten document types.

After Tom's presentation, Mark Silverman, who chaired the symposium planning

committee, will describe the rest of our program. It's a real pleasure for me to be here today. I hope that by the time it's over, you'll feel the sane way.

9
LIFE CYCLE CONCEPTS AND DOCUMENT TYPES

Roy A. Young

U.S. Department of Health, Education, & Welfare

330 Independence Avenue, SW

Washington, D. C, 20201

A good system of life cycle documentation not only specifies how information

is to be recorded, but also when it is to be recorded. It has long been

established that poor or inadequate communication between personnel is a major problem, and it always starts at the initiation phase of a project,

and then continues until the system is terminated.

If documentation is done concurrently with task development, the completion

of each task is signified by the availability of the finalized documents. A

review of the completed documentation during development and after

implementation phases provides the opportunity for assessing progress, and

it can point out problem areas between scheduled and actual dates.

When newly proposed systems are to interface with an existing system, it is

vital to review the interaction between the two systems. This can only be

achieved if the previously designed system is adequately documented.

The first exhibit (Exhibit A) is easy to identify with, because

documentation, in many respects, says about as much as this exhibit. We all

have reviewed this type of documentation at one time or another in our careers. We hope that after the FIPS PUB 38 Symposium today, we can all go

back better prepared, so we don't leave those who come in contact with our documentation frustrated because it lacks the technical explanations and

clarity to be understood.

Many of us, as managers without documentation standards and policy

guidelines, have been confronted with the individual who says, "You do it

your way and I'll do it mine." (Exhibit B) Their arguments are that their

documentation is adequate to do their job. However, we all know that for a new employee given a new project, the documentation in most cases is not

adequate. It is easy to understand the programmer's feelings when it comes

to documentation after the program is operational. But in order to ensure

the continued success of the program in a production environment, it must be

capable of being maintained. Good documentation is the only answer. As has

been pointed out by earlier speakers, "It pays to document." Documentation

is the result of hard work by managers and their staffs (Exhibit C). How

many times have you come head-to-head with the problem of documentation?

The manager says, "Hey! Your documentation is not complete." The programmer

planned on bringing it up to date, but has several excuses as to why he

hasn't documented it. As a manager, we have a responsibility to see that

documentation is kept current with development and finalized upon

implementation.

The delicate position the ADP manager is in when it comes to documentation

is pointed out in Exhibit D. As managers, you are constantly being badgered

by your staff about what is adequate documentation. If you allow substandard documentation to occur, eventually the user or your boss will be

all over you like a tiger. As managers, we know that documentation

standards are necessary to stay out of trouble. We must enforce

documentation standards or suffer the consequences.

The project manager (Exhibit E) has the ultimate responsibility for

documentation. He is the one who must sign off on the system when it is

ready for implementation. He must determine whether the documentation is

adequate, because he must satisfy the requirement that it will support

programming maintenance functions by other programmers.

10
When we talk about life cycle concepts, we mean from inception of a new program or system until its discontinuance. The definition of the

documentation elements of the software life cycle (Exhibit F), as it

pertains to FIPS PUB 38 is as follows:

PHASES . While terminology used to describe the phases is arbitrary, it

provides a convenient framework within which the development of software may

be discussed.

Initiation . During the Initiation Phase, the objectives and general

definition of the requirements for the software are established.

Feasibility studies, cost-benefit analyses, and the documentation prepared

within this phase are determined by agency procedures and practices.

Deve lopment . During the Development Phase, the requirements for the

software are determined and the software is then defined, specified,

programmed, and tested. Documentation is prepared within this phase to

provide an adequate record of the technical information developed.

Operat ion . During the Operation Phase, the software is maintained,

evaluated, and changed as additional requirements are identified.

STAGES. While the terminology used to describe the stages is arbitrary, it

provides a convenient framework within which the development of the ten

document types may be discussed. It is recognized that not all of the

document types are required to document software in every case, and that in some cases, the various document types may need to be combined.

Definition. During the definition stage, the requirements for the software

and documentation are determined. The Functional Requirements Document and

the Data Requirements Document may be prepared.

Design . During the design stage, the design alternatives, specific

requirements, and functions to be performed are analyzed and a design is

specified. Documents which may be prepared include the System/Subsystem

Specification, Program Specifications, Data Base Specification, and Test

Plan.

Programming . During the programmin

debugged. Documents which may be prep

Users Manual, Operations Manual, Prog

g stage, the software is coded and

ared during this stage include the ram Maintenance Manual, and Test Plan.

Test . During the test stage,

documentation reviewed. The software

terms of readiness for implementa

prepared

.

the software is tested and related

and documentation are evaluated in

tion. The Test Analysis Report may be

DOCUMENT TYPES . The purpose of each of the ten document types is defined in

the following paragraphs.

Functional Requirement s Document . The purpose of the Functional

Requirements Document is to provide a basis for the mutual understanding

between users and designers of the initial definition of the software,

including the requirements, operating environment, and development plan.

Data Requirements Document . The purpose of the Data Requirements Document

IS to provide, during the definition stage of software development, a data

description and technical information about data collection requirements.

Sys tem/ Subsy s tem Specification . The purpose of the Sys tem/ Subsy s tern Specification is to specify for analysts and programmers the requirements,

operating environment, design characteristics, and program specifications

(if desired) for a system or subsystem.

11
Program Specification . The purpose of the Program Specification is tp

specify for programmers the requirements, operating environment, and design

characteristics of a computer program.

Data Base Specification . The purpose

specify the identification, logica

characteristics of a particular data ba

User's Manual . The purpose of the User

the functions performed by the software

the user organization can determine

use it. It should serve as a reference

data and parameters and for interpretat

of the Data Base Specification is to

1 characteristics, and physical

s e .

's Manual is to describe sufficiently

in non-ADP terminology, such that

its applicability and when and how to

document for preparation of input

ion of results.

Operations Manual . The purpose of the Operations Manual is to provide

computer operating personnel with a description of the software and of the

operational environment in which the software should be run.

Program Maintenance Manual . The purpose of the Program Maintenance Manual

is to provide the maintenance programmer with the information necessary to

understand the programs, their operating environment, and their maintenance

procedures

Test Plan . The purpose of the Test Plan is to provide a plan for the

testing of software; detailed specifications, descriptions, and procedures

for all tests; and test data reduction and evaluation criteria.

Test Analysis Report . The purpose

document the test analysis results and

capabilities and deficiencies for rev

a statement of software readiness for

of the Test Analysis Report is to

findings, present the demonstrated

iew, and provide a basis for preparing

implementation.

12
6(

I believe you understand what

you think T said but Tm not

sure you realize that what

you heard is not what I

meant."

EXHIBIT A

13
Hey, George! This is supposed to be a team effort.

EXHIBIT

Ik
STAF F M ANAGEHS

15

EXHIBIT C
16
AN ALYST PROCSRAMMER

O C U MEIMTS

EXHIBIT E

17
2

UJ ^ a a

l-Z

UJDU

UJJu>

UJ

u.<h

LL0 <Iah2

lUa0J

Ui>

Ui y tn t a z 20

UJ t CD 2 <

UJ CD D

in*

5^0 £ in u

1"^ I

cn

CO

Ula

cn

tn

cn >D

D 0 U

UlH

Q

U2D

u. 2a<

EE

Ula 2

UJu2

<2

J 2 UJ < ?2

ir < < 2<U

ULu

Ula

cn

(02

UJ ^ I2

Ul UJ 5§a u

UJ 0 a

cn

Cfl 5^- 2Ja

cn

Ul

EXHIBITF 18
FLEXIBILITY PROVISIONS AND DOCUMENT TYPE SELECTION

Robert R. Hegland * Naval Command Systems Support Activity

(Code 70.3)

Washington Navy Yard

Washington, D. C. 20374

[ INTRODUCTION

iMost standards and guidelines are not s e 1 f - imp lemen t ing . To be most

effective, they need to be analyzed by a central office to establish the

policies and procedures to implement them in a particular department or agency. The central office must establish the responsibilities and

implementation procedures that will make the standard or guideline most

useful to its organization.

Discussed herein are those policies and procedures that a central office

should consider in implementing the FIPS Documentation Guidelines. The

authors of the documents that are discussed in the Documentation Guidelines

should be familiar both with the policies and procedures that are established and the flexibility provisions contained in FIPS PUB 38. Anyone

can prepare reams of documentation but it takes some thought and

understanding to produce useful documentation.

FLEXIBILITY PROVISIONS

1. USING SPECIFIED SECTIONS AND PARAGRAPHS

The Guidelines provide ten different document types, each of which has

several sections. Each section has numbered and titled paragraphs within

it. There is some flexibility in using these paragraph numbers and titles.

Authors are encouraged to try to use them as they are structured in the

Guidelines, since a great deal of time went into developing them. Also,

much of the Guidelines is based on a documentation system that has been used

and modified over a number of years, and the sequence is essentially the

same as is used in that documentation system.

o There is the provision within the Guidelines to add specific

program and file names to some of the paragraphs.

o If the author or the central office determines that additional

paragraphs or sections are needed, it is suggested that paragraphs

be added at the end of a section and sections be added at the end

of the document type.

o Sections and paragraphs can also be deleted when they are not

applicable to documenting a particular system. This can be done

in two ways: by simply omitting them, or by including a short

description of why no detailed information is included. An example

of this is a paragraph in the Guideline that deals with security.

If the system is not classified, there is no need to include a paragraph that explains the security provisions for protecting

the system and its data. In either case, the integrity of the

Section and Paragraph numbers and titles can be preserved.

2. AUDIENCES AND FUNCTIONS

Another provision of flexibility that needs to be recognized is that each of

the document types is designed for a particular audience and a particular

function. This concept is very important because of the great variety of

organizational structures that we find in data processing in the various

government departments. A given computer program may be used in one organization by only one person, who acts as the user, computer operator,

and maintenance programmer. In another organization, there may be three

separate people serving those functions for that program. The Guidelines is

intended to be independent of organizational structure, so that it can be

19
used in both situations. Since there are at least three different functions

being performed in each situation, the three different documents should be

prepared —one each addressing the function of the user, the computer

operator, and the maintenance programmer. The function being performed,

rather than the individual looking for the information, determines which

document is referenced.

3. USE OF FORMS

Another provision of the Guidelines is to allow (and encourage) the use of

existing forms in preparing your documentat ion. There are no forms

specified in the Guidelines as being mandatory for documenting a program,

since the format of such forms changes so much from one organization to

another, and since there are elements on some forms that change depending on the particular hardware and operating system you have. It is suggested,

however, that your forms be referenced from the paragraphs that are in the

Guidelines, so that the basic structure of the document types can still be

used, regardless of the forms that you may be using.

4. USE OF FLOWCHARTS AND LISTINGS

Whether or not to include flowcharts and listings in your documentation is

another area where there should be a policy established. Certainly, the

maintenance programmer should have access to these, but there is some question as to whether they need to be included and printed in a document.

It usually is adequate to have them on file, rather than to have them

printed in a formal document.

5. SUPPLEMENTING THE DOCUMENT TYPES

There are several other items, in addition to the flowchart and listings,

that can be used to supplement the document types. These are useful to

remember and use, since the documentation needs to be thought of in a hierarchical structure. The source code is the most detailed level of

documentation; the Program Maintenance Manual is the next most detailed, but

should not be thought of as taking the place of, or being as detailed as,

the source program listing. The source code can serve this function

particularly well if it is well commented. Another supplement can be the

output of an automated flowchart program. It would seem to be unnecessary

to have a printed document of program flowcharts if an automated flowchart

package is available to printout a flowchart whenever it may be needed.

The output of a Data Element Library also can be used to reduce the amount

of typed, formal documentation. This output could either be included in the

Document or referred to from the document.

6. OTHER DOCUMENT TYPES

To have a complete documentation system, you may want to establish some other document types, such as a technical report or technical note--that can

be used to contain supplements studies, or catalogs, etc.

7 . COMBINING DOCUMENT TYPES

Some document types can be combined, in some instances. Those that have

most frequently been combined are: Users Manual, Operations Manual, and

Program Maintenance Manual, to form a Project Manual; several Program

Specifications, to form a Subsystem Specification; and several Subsystem

Specifications, to form a System Specification. This technique may be

particularly useful on small projects, but must be used with some care. After all, each document type is intended for a different audience and may,

therefore, have a different distribution. Additionally, the different

documents will almost surely be completed at different times, so a combined

document cannot be published until the last "piece" is finished.

DOCUMENT TYPE SELECTION

In deciding what document types should be produced for a particular project,

there are two different approaches presented in the Guidelines. Your

20
organization may want to adopt one or the other, it may want to change some

of the factors in one before adopting it, or it may leave that decision to

the project leader.

1. COST/USAGE THRESHOLD CRITERIA

Figure 2 in FIPS PUB 38 presents a technique based on the anticipated cost

or use of the project to determine the document types that need to be

produced .

2. PROJECT COMPLEXITY

Figure 4 in FIPS PUB 38 shows a chart with twelve "complexity factors", each

of which can be assigned a weight or "value" between 1 and 5. When the

values are added together, the overall complexity total can be applied to

Figure 3 in the Guidelines, to determine what document types are needed for

a project of that complexity.

There are some overriding considerations that should be analyzed in deciding

which document types will be produced, such as whether a contractor will be

involved in the project, whether you are automating a previously manual

function, and whether you will be working with an integrated data base.

3. MANAGEMENT CONSIDERATIONS

A. DOCUMENTATION PLAN

One "of the first things that should be done during project development is to

prepare a Documentation Plan to determine what documents will be produced

during the project. Other items that should be considered in this plan are:

o Approximate size (or range) of each document.

o Portions of each document that are and are not needed.

o Level of detail of each document.

o Dates when portions of the documents will be available for

management review.

B. REDUNDANCY

In applying the various flexibility criteria, the question of redundancy

needs to be clearly understood by the central office and the authors of the

documents. There are three kinds of redundancy that have been included

intentionally in the document types:

o Stand Alone. The first section of each document contains

information on the background of the overall project, to

set a frame of reference for the reader.

o Apparent. Many documents appear to call for the same information. The information that is provided, however,

may be different, because it is intended for different audiences,

o Evolutionary. There also appears to be some redundancy between

document types; it provides programmers the opportunity to

document changes that have taken place since prior documentation was produced

CONCLUSION

This has been a brief summary of the different flexibility provisions in the

Documentation Guidelines. There are many factors that need to be understood

before the maximum benefit can be derived from it. The Guidelines is not

"s e 1 f -imp lemen t ing" , and must have the involvement of, and support from, a central office if it is to be used effectively.

* The views expressed herein are those of the author and do not necessarily

represent policy of the Department of the Navy or of any naval activity.

21
CONTENT GUIDELINES

Thomas M. Kurihara

Technical Resources Staff

Data Systems Division

Agricultural Stabilization and Conservation Service

U. S. Department of Agriculture

P. 0. Box 2415

Washington, D. C. 20013

PURPOSE

The, purpose of my portion of the Philosophy of FIPS PUB 38 is to describe

briefly Part 3, the Content Guidelines. The Content Guidelines in FIPS PUB

38 serves to provide managers of development projects with a guide to follow

in prescribing and reviewing project documentation, and writers of documents

with content guidelines.

Part 3 of FIPS PUB 38 outlines and describes the content guidelines for ten

document types that could be prepared during the software development phase.

Before addressing the content guidelines for each of the document type, we must keep in mind the purpose of documentation. These content guidelines

were prepared to provide a vehicle for communication between the user and

development groups. Each document type is intended to be written for and

used by, a specified audience.

AUDIENCES

The audience (or intended reader) may be an individual or a group of

individuals. In the development of automated data systems and computer

programs, there are, in general, two audiences: the user group and the

development group. The user group provides data inputs, uses the outputs,

states the requirements for the development effort, and assumes responsibility for acceptance and use of the system. The development group

performs the design, programming, and test functions.

We recognize that your work environment and individual manager's

requirements will vary. Regardless, it must be emphasized that when each

document type is written, the audience, and its function, should be

identified and understood. Consideration should be given to audience

knowledge and experience, writing style, terminology, and anount of detail.

Elaborating on Bob's description of functions, let's look at the specific

"management" audiences. I will call the first "Approval Management". Their

function is to make decisions concerning the project based on its

contribution to overall organization objectives.

"Development Management" is interested in the amount of change that must be

anticipated; the completeness of user requirements; complexity; mode of

operation; available resources; and system life. Their function is to

develop a set of technical specifications for the final product, from which

program code is prepared and tested. These specifications are translated

from functional descriptions stating user requirements.

"User Management" is concerned with improved efficiency and effectiveness;

better information for decisions; training; and internal procedures. Their

function is to review the development of the system, use the developed

systems, identify performance and acceptance criteria, and train user personnel

The developers are concerned with product performance, correct and complete

specifications, and completing the project on time. The users, on the other

22
hand, are concerned with furnishing data, changing procedures to fit the new

system, and understanding how the new system will affect their everyday

f unct ions

.

Therefore, with an understanding of who the audiences are, the writers of

documentation should be guided by the content guidelines contained in FTPS

PUB 38. The following comments are intended to provide a capsule summary of

each of the ten document types,

DOCUMENT TYPES

Functional Descriptio n

o Describes the development group's understanding of the user group's

requirements for an operational capability,

o Written in "user language", minimizing technical terminology about

ADP hardware,

o Contains an analysis of methods, impacts, cost, requirements, and

operating environment,

o Submitted to the user for concurrence, and to user management for

approval, prior to preparing detailed system specifications,

o Basic reference document for determining the impact of any change

to the scope of the project made prior to user acceptance,

o Contains a development plan identifying milestones and participation

by other organizations.

Data Requirements Document

o Describes the development group's requirements for data, and the user group's data collection effort to establish and maintain system

files . o Written in user terminology.

o Contains descriptions of input data, procedures and constraints in

data handling, expected outputs, and specifications of data elements,

o Submitted for user concurrence; serves as a source of data

specifications for the development group.

o Basic reference document for description of data.

System/Subsystem Specification

o Describes the system structure, function, and flow to analysts and

programmers in the development group, at a level of detail beyond

the functional description,

o Written as a technical document, in enough detail to carry out

program design and coding,

o Contains performance requirements and design logic for the

system/ subsystem,

o Submitted to development management for review and approval,

o Defines the types of interfaces with other sy s t ems / subsy s terns and

the operating environment,

o Basic reference for assessment of impact of design changes approved

by the user, within the scope of the described system.

Program Specification

o Describes the program requirements to analysts and programmers in

the development stage,

o Written as a technical document, in enough detail beyond the system

specifications to describe adequately the component functions,

outputs and performance to permit program coding and testing,

o Contains performance requirements, instructions for operations, data

structures, and program logic,

o Submitted to technical development management for review and approval.

23
Data Base Specification

o Describes the attributes of data bases, and data elements contained

therein, when several groups are involved in maintaining and using

the same data base.

o Written in data base terminology, for use by programmers and by data

base managers.

o Contains detailed information to permit coding, data base generation,

and maintenance.

o When a data base management system is used, this document may

supplement the DBMS documentation,

o Alternative formats are described; however, to achieve consistency

in presentation, the following practices should accompany the use of

this document type:

- Establish the order of contents; for example, as given in the

content guidelines.

- Follow each item description with the formatted arrangement

of data

- Descriptions and naming conventions should be consistent with

your data base administration policies and conventions.

User's Manua

o Describes how the user group will use the automated data systems and

computer programs prepared by the development group,

o Written in user format, with user terminology.

o Contains instructions and procedures for data entry, equipment

operations, interactive queries, and sample outputs. Sections

1 and 2 are directed toward user management. Sections 3 and 4 are directed to the users.

o Submitted to user management and staff for approval, and may be

used as basis for training.

o Basic reference document for determination of the impact of changes

on procedures, and impact of computer system changes on procedures.

Has the equivalent level of detail for users as the Program

Specification does for the development group.

Operations Manual

o Describes how the computer operations personnel will initiate, run,

and complete processing of the job.

o Written in operations terminology, and usually follows a step-bystep-scenerio.

o Contains instructions and procedures for routine operations and for

recovery (i.e., non-routine operations),

o Contains instructions and procedures for remote terminal operations,

if they are required for data entry or remote batch operations.

Program Maintenance Manual

o Describes the accepted, operational computer programs for the

maintenance programmers, who are responsible for making changes

to those programs. The design approach, program logic, related

data, and operating characteristics are described.

o Contains diagrams and listings of source code for the operational

version of programs, and narrative explanations of interfaces,

parameters, codes, and messages.

o Describes interface and dependencies with the operating system.

o Provides a history of changes within the scope of the original

requirements,

o Refers or contains test information and test data.

24
Test Plan

o Describes the test plan, testing procedures, test criteria, and

evaluation criteria.

o Written as a non-technical document for users and staff personnel

conducting tests; and in appropriate technical terminology for

analysts, programmers, and operations personnel,

o Contains test specifications and details concerning the step-bystep testing procedures,

o Testing procedures should cover all interfaces among system/subsystems, programs, and data bases; and describe the relationship

among test programs or functions,

o Test methodology, data, and results should be retained for verification of the tests.

Test Analysis Report

o Describes the results of the test.

o Written for management, describing the test results for management

decision regarding the acceptability of the product. Results should

be compared to the operational requirement and performance

capabilities to assure that all design changes have been incorporated

o Describes deficiencies and corrective actions necessary for acceptance or, if the deficiency is not corrected, the impact on the system

o Contains explicit user acceptance in his statement that the system is

ready for operation,

o List of improvements which can be made in design or operation of the

system as determined during the test period.

CONCLUSION

With an understanding of the audience and content guidelines, the writer of

documentation can now turn to the preparation of project documents using his

respective Agency style, forms, and format conventions.

FIPS PUB 38 has, as a Federal guideline, a high degree of flexibility in its

application and implementation. Any and all feedback to TG14 concerning

your experiences in using it will provide us with the information needed to

make the changes to better suit Federal ADP managers.

25
DESCRIPTION OF AFTERNOON SESSIONS

Mark Silverman

Technical Staff Assistant

U, S. Geological Survey

National Center, Mail Stop 801

Reston, Virginia 22092

For the remainder of the symposium there will be three parallel sessions, as

f ol lows

Session A , which is slanted towards executives, user managers, and project

managers, will be moderated by Robert V. Head, Mr. Head is the Assistant

Director of the Office of Automated Data Systems at the U.S. Department of

Agr,iculture . He has been with the Department since 1971, and has held

several key positions as a computer executive. Before entering government

service, Mr. Head worked for several years as an information systems

consultant. From 1963 to 1965, he served as Vice President in charge of

systems planning for Security Pacific National Bank. He was associated with

International Business Machines from 1959 to 1963, first as a senior systems

engineer and later on the staff of the IBM Systems Research Institute.

Earlier, he worked as a manager and programmer for General Electric and

UNIVAC. Mr. Head holds the Certificate in Data Processing of the Data

Processing Management Association, has twice served as a National Lecturer

of the Association for Computing Machinery, and is a past President of the

Society for Management Information Systems, He served as a Contributing

Editor of Pat ama t ion magazine from 1965 to 1971, He is the author of three

books and more than 40 papers in the field of business systems. He received

a B.A. in Government from George Washington University, where he was a member of Phi Beta Kappa,

Session B should be of interest to ADP Systems, Operations and Programmer

Personnel, and will be chaired by Thomas P. Giammo. Mr, Giammo is the

Director, Division of Statistical Processing, at the Social Security

Administration. In this capacity he is responsible for the computer

processing of all internal management, administrative, and statistical

research activities of the Social Security Administration. Before joining

the Social Security Administration, Mr. Giammo was Deputy Director, Data

Management Center, at the Department of Health, Education and Welfare.

Prior to entering government service, he was Director of the Washington

Computer Center of TRW Systems, and he also was associated with Gulton

Systems Research Group, Inc. as Vice President. Mr, Giammo received a B,S.

in Math from R,P,I. and a M.A, in Math from U.C.L,A,

Session C , which is aimed at those of you who are interested in Standards,

Training, Policy, and Audit will be chaired by Harris G. Reiche, Mr, Reiche

is Director of the Office of ADP and Telecommunications Management,

Department of the Interior, He is responsible for policies, planning, and

reviews pertaining to the acquisition and management of automatic data

processing and telecommunication resources throughout the Department of the

Interior. During 1974-75, he served as Chairman of the Government

Interagency Committee for Automatic Data Processing. He came to the

Department of the Interior in September 1973, with the responsibility for

establishing a Department ADP management organization. Previously, Mr.

Reiche had served 22 years with the Department of Defense —since 1957,

within the data processing field, where he served primarily in ADP planning

and policy roles with the Department of the Air Force. His last assignment

prior to joining Interior was as Director of Policy, Technology and

Standards, in the Office of the Secretary of Defense. During this period,

he also served on the Information System Technical Advisory Board of the

American National Standards Institute. Mr, Reiche received a B,S. in

Business Administration from the University of California, Berkeley and an M.S. in Information Systemsl-rom George Washington University.

26
USDA APPLICATION MANAGEMENT

Robert V. Head

Office of Automated Data Systems

U. S. Department of Agriculture

Washington, D. C. 20250

Let me begin by providing a brief profile of the Department of Agriculture's

ADP operations. In terms of size, we fall between the two other members of

this panel. We are a lot smaller than DoD, and somewhat larger than HUD;

with an ADP budget of about $65 million. Approximately two-thirds of our ADP funds are devoted to application development and maintenance, so the

subject of documentation standards has obvious importance for a manager who

is concerned with where the dollars are going.

In general, our environment can be described as one of centralized data

processing and decentralized application development. We operate, in the

Office of Automated Data Systems, four computer centers, and these centers

serve 25 using agencies and staff offices. Thus, we have a somewhat

centralized operations set-up and a highly decentralized user organization

in which application development work is taking place.

The main vehicles for disseminating ADP policy and standards information

within USDA are the Departmental Information Processing Standards manual and

Title 11 of the Administrative Regulations of the Department. We have

sought to introduce FIPS PUB 38 material into both of these documents.

We have adapted the system development life cycle found in FIPS PUB 38, and

published it in our Departmental Information Processing Standards manual.

We are concentrating on documentation during the initiation phase of a project. The reason for this, thinking in terms of management control over

ADP resources, is that this is the point at which both executive managers

and project managers should see some documen t a t i on--be f ore the project has

gained approval or moved into the development phase. ADP resources are scarce, and we have projects competing for these resources. We would like

our managers to look at each project proposal critically while it is in the

initiation phase, or at least before it has gone beyond the definition stage

of the development phase. So we've identified documentation requirements

that apply both to all USDA agencies and central staff offices. We have

tied documentation into a managerial approval process. We believe that by

emphasizing the initiation phase and emphasizing the role of management

approval based on FIPS PUB 38 type of documentation, we are orienting our work towards managerial interests.

In the Agricultural Regulations, we require that each agency of the

Department with a significant ADP budget set up an Application Review Board.

We define significant as a million dollars in budget, or more. Agency ADP

budgets within USDA range anywhere from $5,000 a year to more than $15

million per year. A dozen or so are spending a significant amount of resources on ADP, and have established Applications Review Boards.

The chairman of each board is at a top management level within the agency.

We suggest the level of Deputy Administrator for Management. There also

should be membership on the board by people who represent the program areas

of the agency--the important mission areas of the agency.

As we structure our boards, we do not have the information systems director

of the agency serving on the Board. We view the Board as engendering a sort

of adversary relationship between the systems development staff and the top

management of an agency. The Board is there to look critically at

application proposals, to challenge them, to try to make resource allocation

27
decisions based on top management's viewpoint, and not on the viewpoints of

the technicians in the organization.

The Application Review Boards are charged with reviewing planned

applications during the initiation phase, again tied into the FTPS PUB 38

life cycle. A major application must go before the Board for review while

it is in the initiation phase. A major application, for purposes of Board

review, is one on which $50,00.0 is expected to be spent during the life of

that application.

The Board must review all Automated Decision Making Applications (ADMA's),

regardless of size. Similarly, the Board must review any planned

application, regardless of size, that processes personal information, as defined by the Privacy Act of 1974.

Among the responsibilities that the boards are charged with are:

1. To review cost-benefit analyses of applications.

2. To assign priorities to applications in accordance with

their cost-effectiveness and their importance in meeting

the program requirements of that agency.

3. To review the implementation schedules of proposed projects

in terms of the agency's mission requirements.

There is a form that is intended to help in the review process. The

"Request for Agency Planning Data" form is geared to the philosophy and

terminology of FIPS PUB 38. It has^ two major parts. The top part covers

the application initiation phase, the bottom part the application

development phase. This means that in the life cycle of a project, two

forms must be completed and submitted for review as the project moves through <3ie initiation phase into the application development phase.

There is a date to be provided, which represents the time at which

management approval has been secured for a project. There is another date

to be filled in which indicates when a cost benefit analysis has been

completed for the project. There are also provisions for estimating

schedule dates and summarizing cost estimates for the project.

During the initiation phase, we ask for a rather gross indication of what

the dollars estimated to go into the project will be. If the project leaves

the initiation phase and proceeds into the development phase, there is some additional cost information that must be provided. Within the development

phase, we ask for a breakout of schedule dates and estimated costs for each

of the steps within that phase. At this point, those most concerned with

the project should be able to do a more precise job of estimating their

costs. The important thing to emphasize here is that through our procedures

and through our high level documentation, we have adapted the life cycle

concept of FIPS PUB 38 and some of its substantive information content to our management approval process.

I don't want to mislead anyone by indicating that the system is fully

installed and operating smoothly. It is very new in several respects.

There are pieces that are missing. For example, we still don't have

satisfactory guidelines for doing cost benefit analyses. We look to NBS for

further progress in guidelines that will aid in managerial decision making.

28
DOCUMENTATION STANDARDS - A MANAGEMENT VIEW

Eugene B. Data Systems & Appl

Agricultural Res

National Agricultural

Beltsville

,

Smith

ication Division

earch Service

Library - Room 003

MD 20705

Variations in data processing activit

out the need for flexibility in the e documentation standards. This paper

the real and perceived value of d integrating certain elements of the sta

ies and documentation practices point

stablishment and implementation of

will briefly explore the thesis that

ocumentation can be increased by

ndards into the management process.

Documentation Style - One may disagree with specific terminology presented

in FIPS PUB 38, but it does represent the traditional approach to

documentation. Since the concept is presented as a set of guidelines, an agency has considerable flexibility in implementing standards. Compliance

will impose a certain amount of formality, which is desirable. In addition

to improved applications systems, a significant benefit from compliance

should be improved management procedures in the areas of control,

cost/benefit analysis, and planning.

Last Fall I took my graduate students to visit two major oil-related

companies in Houston. During the course of the visit, we questioned each of

these large companies about the level of documentation required in the

development of new applications.

The first company's documentation practices were relatively formal, and by

way of implementation they routinely utilized a standards and procedures

manual which was about 400 pages long. It was comforting to note that the

traditional textbook approach was actually being followed out in the "real"

world .

The second company's approach to documentation standards and procedures was completely informal. They had no published standards, and required very

little documentation other than a series of working programs. Their

approach was that there would always be more than one person available who

was intimately familiar with each system. When questioned about the need

for a more structured approach, the director indicated that they were results-oriented and could not afford the luxury of more documentation.

The data processing operations of both companies have been successful for

many years. The different approaches represent different management styles,

and the success of the informal approach may, in part, be attributed to a certain amount of luck.

This contrast in approaches tends to highlight the question of perceived

cost versus benefit. What priority do we place on documentation in terms of

a completed system? Can we afford to provide adequate documentation? Can

we afford not to?

If we were to conduct a documentation audit of a number of DP operations, I am convinced that we would find a very small percentage actually following

adequate documentation practices. Why should this condition exist? Would

we purchase a software package, which we had to maintain, that was seriously

deficient in documentation? Probably not.

Unfortunately, too often, we do not consider documentation to be an essential element of internally developed systems. We want to get the

system working, and don't really have time for documentation. We fail to

recognize that good documentation can significantly impact the value and

29
usefulness of a system. Documentation is more statements in a program. It should be viewed as an system, and a useful management tool.

than just

integral

a few

part

comment

of the

QUANTITY

APPLICATION SOFTWARE DEVELOPMENT - PRODUCTION PER UNIT OF RESOURCE

There seems to be a conflict between quality and quantity, as indicated by

Curve 1 on the above Figure. In considering the production of a DP

organization, it is possible that, by the routine use of good documentation

standards, the level of quality for a given quantity of work could be

increased, as shown by Curves 2 or 3.

D ocumentation Survey - While conducting an internal study to assist in

developing documentation standards for the Agricultural Research Service, it was decided that there might be some value in a survey of some 20 sister

agencies. The survey was intended to provide a vehicle for determining how

documentation was being handled by other agencies, and to allow the

collection of documentation material which might be of assistance in our endeavor

The size of the data processing function varied widely from agency to

agency. Agency budgeted expenditures ranged from about $24,000 to over $16,000,000. Numbers of data processing related employees, ranged from 1 to over 400. Project size ranged from less than one man day to several man

years of effort.

While it was possible, during a brief visit, to get some idea of the nature

of the standards available, it was not possible to observe how well the

standards were being utilized. In terms of existing standards, it is safe

to say that they varied from non-existent to very good. Generally, the

agencies with few DP professionals needed the most improvement in standards.

Some agencies receive DP support from other agencies, and have virtually no standards of their own. Essentially, they accept the documentation

provided. Some agencies "contract out" major projects to commercial firms.

In these, the documentation is included as part of the contract, and the

results seem to be generally good.

The agencies with large DP professional staffs seemed to be more concerned

with the status of documentation standards, and with control over their use. There were a couple of notable exceptions, where relatively small staffs

placed a special emphasis on documentation. Two agencies had recently

initiated major efforts to develop new documentation standards in compliance

with the FIPS and DIPS (our departmental guidelines) publications.

Since FIPS PUB 38 recognizes four levels of documentation, based on usage

and cost factors, it is flexible enough to accommodate the range of

variation found in the survey. In general, there seemed to be no

30
disagreement about the need for documentation, nor was there any quarrel

with the guidelines embodied within the FIPS and DIPS publications.

Imp roving the Perceived Value of Documentation - It should be possible to

integrate mu c h of the minimal (or level O documentat ion requirements into

the internal management control system. Much of the information desired for

documentation, is also needed for management. If standard documentation

practices are not adequate, one may question the adequacy of management

prac t ices

.

Consider the types of information generated throughout the Software Life

Cycle, The information assembled in the initiation phase corresponds to the

types of information required to plan, organize, and manage the effort of a DP organization.

It should be possible to design a Service Request Form that would serve both

the documentation and management processes. Such a form could include the

following types of data:

DESCRIPTIVE PROJECT DATA

TITLE

ABSTRACT

CONTACT

DATE REQUIRED

CONSIDERATIONS - Privacy

- Security

- SPECIAL

TYPE OF REQUEST

PROJECT CONTROL DATA

PROJECT NUMBER

RESOURCES REQUIRED - SALARY COSTS

- COMPUTER COSTS

- OTHER COSTS

ASSIGNMENT DATA

TARGET DATES

The minimal documentation level would also include other material, depending

on the nature of the project. Higher documentation levels would include

additional elements, as described by FIPS PUB 38. An integration of

management and documentation procedures provides a necessary element of

control . One might emphasize the point that "The Job is Not Finished Until The

Paperwork Is Done." The existence of good standards does not necessarily

mean that they are implemented in day to day practice. The enforcement of

standards requires a continual effort by management.

31
KEY ELEMENTS IN THE ADP SYSTEM DEVELOPMENT PROCESS AT HUD

Dr. Mar

Acting Deputy Director, Off

Department of Housing

Washington

in Goer

ce of ADP System Development

and Urban Development

D. C. 20410

The Office of Administration has been restructuring the procedures and

organizational responsibilities associated with the development of ADP

systems and operation of HUD ' s ADP capabilities. The basic intent of these

actions is to: increase efficiency, provide more responsive service,

provide for more orderly and systematic ADP planning and budgeting, and

provide for the control and accountability of our total ADP resource

utilizat ion

HUD Handbook 2360.1, "Planning Guidance for ADP Data Systems Development",

will probably be superseded by a new set of manuals which will incorporate

changes to accomplish these objectives. In order to provide HUD's

programmatic managers and ADP users with guidelines, and to assist them in

continuing with their ADP development planning, while the Handbook is in the

revision and clearance process, ADPSD has prepared a description of the ADP

system development cycle showing the traditional system development cycle as

it is affected by the revised policies. This guidance should be considered

interim, even though these same concepts are serving to structure the

Manual s

The new Manuals, when they are issued, will incorporate a new conceptual

approach. The ADP System Development cycle will be covered comprehensively,

from Initiation and Requirements Analysis through Budget and Resource

Allocation, Specification, Design, Programming, Test and Development

Implementation, Acceptance, Operation, and Maintenance.

The purpose of this paper, therefore, is to describe how the ADP system

development process is intended to be implemented. Of necessity, the

description is of a normal sequence, recognizing that there may be exception

conditions determined by overriding Departmental priorities.

The charts which follow deal with four (4) major classes of ADP application

systems. While it is always difficult to define precise boundaries, we believe the definition of each major classification is sufficiently precise

to differentiate among the vast majority of HUD's ADP application systems.

Application Systems Types:

A. User Unique — These applications have the following characteristics:

1. They are not mandated (Handbook).

2. They are generally relatively small.

3. They generally do not require routine and frequent use of

internal HUD computing capacity.

4. They may be "one-time" or have a short life-cycle.

5. They generally address a local or limited organizational,

administrative or programmatic need.

B. Single User/Single Program - These applications have the following

characteristics:

1. They are mandated (Handbook).

2. They are for Department-wide operation or use.

3. They are devoted to a single Program (or set of related Programs)

or a single organizational element (or set of related elements

within an organization).

4. They are generally operated in HUD equipment.

5. They are routinely and frequently scheduled for operation.

32
6, They have a relatively long forecasted life utilization.

7. They are generally maintained and operated by HUD personnel.

C, Single User /Mu 1 t i-Progr am or Organization - These applications have

the following characteristics:

1. They are mandated (Handbook).

2. They are for Department-wide operation or use.

3. They are generally functionally oriented, wherein the function

is delegated to a single organizational element with oversight

or support responsibilities across Programs and/or

organizational elements.

They are generally operated in HUD equipment.

They are routinely "and frequently scheduled for operation.

They have a relatively long forecasted life utilization.

They are generally maintained and operated by HUD personnel.

D. Mu 1 t i-User /Mu 1 t i Program or Organization - These applications

have the following characteristics:

1. They are mandated (Handbook).

2. They are for Department-wide operation or use.

3. They are generally in support of combinations of functions

and Programs which cross organizational and Program

e lement s

.

They are generally operated in HUD equipment.

They are routinely and frequently scheduled for operation.

They have a relatively long forecasted life utilization.

They are generally maintained and operated by HUD personnel

The "lead" responsibility for performing each task and for developing the

system products, which are enumerated, is indicated by the first code in

each cell. Tasks and products which require support from, and coordination

with, additional organizational elements are indicated by the codes

following the lead indicator. (U = User organization, S = ADPSD, 0 = ADPO, D

= OMI-DBM)

ADP SYSTEM DEVELOPMENT CYCLE (BY TYPE)

1. SYSTEM INITIATION AND

REQUIREMENTS ANALYSIS A B c D Initiation U u u U

Progr amma tic Requirement/Priority u u u u Operational Schedule u u u u Scope/Volume u u u u Expected System Life u u u u Operational Concept u u U/S/D u/s,

Designate Project Leader u u s s

This is the traditional first phase in the identification of a system

requirement. Frequently it has been referred to as "need identification".

Included in this phase is a first estimate of benefits and costs. The

product of this phase - "The Operational Concept" - becomes an initial input

to the planning, budgeting and resource allocation processes. ADPSD and OMI

will support Users in performing these tasks as required.

A requirement is then merged with all others and a schedule is developed,

priority established, and resources are allocated to develop a system(s) to

meet the requirement. Following these actions, the development cycle

cont inues

.

33
2. SYSTEMS SPECIFICATION A BCD

Prepare System Plan U U/S/0 S/U/0 S/U/0

Data Element Definition U U/D S/U/D S/U/D

Data Sources u U/D S/U/D S/U/D

Data Base Review U/D U/D S/D S/D

Input Specification U U S S Output Specification U U S S Staffing Specification U U U U

Training Specification u u S S Concurrence by Program Office u u u U/S

Contractor GTR (if applicable) U/S s/u s S

In ,this phase of the development process the requirement is defined more precisely, and a system's operational characteristics are specified. The

input data and sources are identified and reviewed by the Data Base

Administration staff, the processing tasks are specified, etc. In addition

to the Data Base review task. Staffing and Training Specifications are identified as discrete tasks to be accomplished and documented. Obtaining

the concurrence of the "end-user" in the system plan and the specifications

are also identified as specific tasks in this phase.

COMPUTER SYSTEM DESIGN A B C D

General System Design U S S s Input Processing U S S S File Creation & Maintenance U S s S Output Processing U S s s Compu t er / Communi c a t ion Design U S/0 s/0 S/0

Maintenance & Operational Concept U S/0 s/0 s/0

Contractor GTR (if applicable) U/S S s s These tasks comprise the basic computer system design effort - sometimes

referred to as the "system architecture". The work is largely of a technical ADP nature and results in Design Documents in which the structure,

relationship and logic of the various system components are described. A

related document is the Maintenance and Operational Concept in which the

hardware and application system relationships are described and the

necessary operational conditions, i.e., storage, line capacity, processing

sequence, manual processing cycles, etc. are documented. In addition, the

logic and discipline for the routine operation and maintenance of the system

is described

PROGRAMMING A B c D

Inptit Processor(s) U S s s File Maintenance Programs U S s s Output Programs U S s s Subsystem Test U S s s Total System Test U S/0 s/0 s/0

Computer System Resource Specs. U S/0 s/0 s/0

Communication System Resource Specs. U S/0 s/0 s/0

These tasks relate to the actual programming and test of the computer

programs. A resultant product is the computer and Communication Resource

Specifications, basically a further detailing of the equipment and

communications resource requirements.

34
5. TESTING AND IMPLEMENTATION A B c D Operator Manuals U S s s Handbooks U U u U

Operator Training U S s s Data Input Training U s s s Program/Manager Training U u/ s u/s u/s

Processing Flow Establishment TTU

TT / C u/ s u/ s D/ S Pilot Test D s/u s/u s/u

Test Evaluation u s/u s/u s/u

User Support Plan u S/U/0 S/U/0 S/U/0

In this phase of the cycle the system products are subjected to test. In

order to accomplish the test (either for Field or CO systems) the supporting

training and documentation tasks must also be accomplished, and coordinated

planning must take place.

ACCEPTANCE, TURNOVER, OPERATION A B C D Criterion Definition U S/U s/u s/u

Test Conduct U S/U/0 S/U/0 s/o/u

Test Evaluation U s/u/o s/u/o s/o/u

System Installation U U/S/0 U/S/0 s/o/u

Turnover (Acceptance) U u u u System Operation U 0 0 0

Before a system is released for operation, the conditions which define

acceptability must be determined (along with measures), and tests conducted

to demonstrate their achievement.

7. SYSTEM MAINTENANCE A B c D Technical Assistance U 0 0 0

Modif icat ions U S/U S/U s/u

Enhancement s U S/U s/u s/u

Upgrades u S/U s/u s/u

The system is now in the operational inventory, and is being utilized in

accordance with the operational concept and specification previously

defined. All systems require continuous attention, and must be periodically

refined to suit changes in operational needs. In most instances, major

changes to existing systems, to incorporate new functions or to broaden the

scope of coverage, will recycle through the development process starting

with the Initiation Phase.

35
SYNOPSIS OF QUESTIONS AND ANSWERS FROM PARALLEL SESSION A

Greg Loss

Public Health Service

Tom Kurihara

Agricultural Stabilization & Conservation Service

Que s t ion : Is there an awareness by management of the cost of implementing standards

such as FIPS PUB 38? My experience has been that a r u 1 e-o f- thumb estimate

to be added to the cost of a project for documentation of a large system is

20-30%. This is not excessive, however, the realization of the cost of

documentation must be addressed.

Smith ; Agree that there is an additional cost.

McGr eer : There doesn't appear to be a history of the cost of documentation.

Head : Is there a danger of over-documentation? In USDA, the Application Inventory

Forms were developed to obtain information from the agencies in USDA on major applications. We were concerned with compliance and the implications

of too much documentation.

Audience Comment : Must look at documentation costs in perspective, i.e., there is a danger in

looking at the "front-end" costs only, whereas taken as part of the cost of

the system over its entire life, the cost of documentation is in its proper

perspective.

Smith : Compare training and education costs to documentation costs. Aren't the

training and education costs of an organization justified in terms of the

return gained from the investment?

Goer : At HUD, we have tried to address the problem of cost by establishing

criteria for the amount of documentation, as described in my presentation.

Kur ihar

: Documentation is the end product of the system development activities. It serves as a record of what decisions were made. TG 14 did not, because of

its limited scope, address the system development activities or the

management activities. Given a management process with estimation

techniques, the cost of documentation can be tied to management and project

activities, and, therefore, be placed in its proper perspective.

Head : In my experience, in recent years, I don't recall that management has asked

about the cost of documentation and training.

McGr eer : The costs must be addressed, because we need top management support of the

standards development effort. There is the danger that as soon as a successful standards effort is developed, such as in the Department of Navy,

there is a tendency to downgrade the Standards Group. Top management should

be provided with the potential savings resulting from a successful standards

development and maintenance effort.

bring to top management attention the need for

the cost of not having it?

Que s t ion : Has anything happened to

documentation standards and

McGr eer : There is the example of the computer security reporting requirements. Top

management attention was obtained when a GAG report was issued. I know that

we can't always go up to GAO and down the ladder again to get top management

attention on everything. Go to your top management and ask for their

support, CRUSADE for recognition to save money in the long run.

36
Goer ; Again, we are in a political environment. There is a tendency to want to

hurry and expedite systetna development because some senior managers want to

make an impact quickly and leave it to the bureaucracy to tidy up later.

The bureaucracy, in the long run, must document to maintain the systems

developed as quick solutions.

Audience Comment : I review the systems on paper, i.e., documentation, as a regular part of my

job. The basic authority is derived from the Budget and Accounting Act of

1950, wherein GAO has the responsibility for approval of all budgeting and

accounting systems. There is a need for more management pressure to develop

documentation standards.

Head

:

We appear to be a group of computer professionals talking. Are we talking

to each other, or is top management here to benefit from this joint selling

effort by NBS and CSC?

Audience Response : Have to use the " c ar r o t / s t i ck" approach. Prepare good documentation during

the implementation stage, and present it to top management for their

decision on continuation of the project. Show how good documentation

supports the decision making process, and provides a basis for potential

cost savings or avoidance.

Head : USDA is committed to the life cycle concept with what we call "creeping

commitment" via project documentation. Documentation is the mechanism by

which projects are reviewed at each stage and phase of application

development. It is the means of bringing management back into the decision

cycle as you go on. Goer : Good documentation can be your protection against GAO reports. On the

positive side, programming is still an "art-form." As a writer, a programmer is forced to write with increased precision and definition when

describing the computer program. Managers get better controls and avoid

surprises as better documentation is provided. Real benefit to management

at all levels is control.

Que 8 t ion : What is the cost?

Goer : The price of documentation in the process of delivering a completed product

is really a "sunk cost" in the bureaucracy. What is most important to me in

the control I have over that process when good documentation is available

for each decision point in the life cycle.

Head ; We should move on to avoid the preoccupation with cost. In any selfregulating mechanism, as dollar costs increases, a method of getting

management involvement evolves. Richard Nolan's Harvard Business Review

Article "Managing the Four Stages of EDP -- Growth and Preparing for the

Fifth Stage" describes the stages of EDP development and the different

degrees of management involvement.

Question : Has the valtie of documentation been addressed in respect to computer program

maintenance? The savings resulting from improved maintenance productivity

can decrease the number of maintenance programmers, and add to the

development group.

Goer : Usually what happens, because of the political climate we are exposed to, is

that if an estimate is made to management of eight months with

documentation, or six months without, they will say go with the six months'.

37
Head ; In the Federal Government, in my experience, there is a general lack of

continuity between the requirements statement and maintenance of the

program. The primary concern is to get it up and running, and avoid the

issue of maintenance. On the other hand, there is a greater concern for

continuity of development and maintenance for commercially developed

s o f twar e

McGreer : Take the life cycle approach. The cost of documentation is repaid over

time. The SAGE system maintenance problem was created as a result of having

a cascading series of different equipment driving the automatic projection

at the command center. The programs had to contain performance profiles for

aircraft and weapons systems. Changes were needed as aircraft and weapons

changed. The cost savings were realized in making the changes more easily.

Audience Comment : I think I have a feel for the maintenance cost. In our organization, I run only a maintenance shop, we do not accept any software for maintenance from

the development shop without usable documentation. We use our standards as

a basis for judgment. Of course, there are roughly four orders of magnitude

in documentation and maintenance. It goes from the 1401/650 programs still

being run, which, taken overall, takes 2 man-years to maintain; to the well

documented system, which can be changed in a day or two per month.

Question for Mr. Head and Dr. Goer ; How does your agency currently control and audit your Department's

compliance with your standards program? What plans do you have in the

future for this control?

Head ; In USDA, we work closely with the internal Office of Audit (OA) staff. OA

is staffing up to be able to address auditing of the system development

process. We have had to be careful to avoid ove r- do cume n t a t i on , and

therefore tried to establish threshold values for submitting application

documentation for approval; e.g., not for systems with an annual cost of

less than $25,000.

Goer : Our problem is smaller and easier to manage. The Assistant Secretary for

Administration is charged with the responsibility for controlling systems

used strictly within his area of responsibility. We do that through a staff

function which combines standards, quality assurance, and quality control.

He cannot control systems which are being developed in other areas under the

other Assistant Secretaries.

Smith ;' One agency I surveyed ran uncertified programs as stand-alone jobs until

they could be certified. They would then be eligible for cataloging to the

productionlibrary.

Audience Comment;

We at GAO visit various agencies to review systems and to assess the

readiness of documentation prepared in support of computer systems.

Question for Dr. Goer;

You mentioned that you do not document those systems which prepare

Congressional reports. In those instances where Congress might find the

system useful, and in fact, decide to fund on a priority basis, how do you

then go back and document?

Goer ; One time requests for retrieval are recorded for effort and accomplishment,

but are not documented. Because they are one time data extractions through

a DBM language, a new DB was not created.

Question;

38
Are states expected to comply with these standards (FIPS PUB 38) on systems

developed with, or supported by, Federal funds?

McGreer : Over time, there will eventually be some type of compliance, if the Privacy

Act of 1974 can be used as an example. The efficiency considerations will

eventually push in that direction.

Head ; I believe that 0MB Circular A-90 specifically addresses that question. It

prohibits any strings to be attached to grants, or on other requirements

levied by the Federal programs.

Kur ih ara : There is a non-profit firm. Public Technology, Inc., which is assisting

local, municipal, and state governments on the exchange of technology under

the sponsorship of HUD. They have developed some documentation standards

for exchange of information about computer-based systems. Generally, the

concepts are transferred, and the implementation of a transferred system is

accomplished with sufficient changes to suit the receiving organization.

But there is a tangible benefit of having standard documentation guidelines

as a supplement to personal contact. The participating local, municipal,

and state government representatives all agreed that the standards developed

in their group will be beneficial. A member of FIPS TO 14 was an observer

at the working group sessions.

Question : How IS TG 14 organized to assist in using FIPS PUB 38? What is the schedule

for issuing the feasibility study, cost benefit analysis guidelines?

Kur ih ara : Thank you for providing us with the opportunity to announce the activation

of a subgroup chaired by Mr. Roy Young, DHEW , to provide assistance to users

of FIPS PUB 38. We are ready to provide the required assistance.

Audience Comment : The review process in the maintenance of the DOD standard has worked. It can v;ork the same way at the Federal level. We are now working on the

second revision to 4120-17M. The first revision is in the publication

process. As people get more familiar with the standard,' they have more

input to it and we are continously getting new ideas. (For further

information, contact Don Wagus, US Army Computer Systems Command, 664-4411).

Head ; In closing, I will use the 5 questions listed on the symposium program to

try to review what we discussed.

Can the guidelines help?

- A qualified YES. There is a need to seek management review at the

ADP policy level.

- How can the manager evaluate technical documentation?

Levels of documentation standards should be identified with the lower

levels, so that top management can handle onlj' the appropriate details.

Is documentation worth the cost?

Much concern and preoccupation with cost. Benefits can be obtained

by making presentations to top management, showing that the series

of documents produced during the development period are a means of

clarifying requirements, improving the effectiveness of the development effort, and easing the maintenance of systems.

- How can software quality be assured through documentation?

A better understanding of software results from improved documentation.

- Do existing systems need to be documented?

Existing systems need to be documented as changes are made. For the

technical people, you must devise methods of getting management attention to support good and complete documentation.

39
INTRODUCTION: ADP SYSTEMS, OPERATIONS, AND PROGRAMMER PERSONNEL

Thomas Giammo

Social Security Administration

Health, Education, and Welfare

Baltimore, Maryland 21235

Welcome to Session B - "ADP Systems, Operations, and Programmer Personnel" - As one can tell from the title, th-is session is designed to explore those

aspects to FIPS PUB 38 which affect the working level personnel of a data

processingoperation. , My name is Tom Giammo, and it's my function to serve as moderator of this

session. Before introducing the members of the panel, I would like to go over some of the ground rules I intend to follow in this session.

First of all, I've asked that the discussion and question/answer phase of

the session not be taped. The introductory addresses of the panel members,

however, will be taped, to assist in the preparation of proceedings.

Although it would have been helpful, in this regard, to tape the discussions

(since a synopsis of these will also appear in the proceedings), I felt that

it might tend to inhibit open discussion. The primary purpose of this

session is to initiate a frank and open dialogue between TG-14 and the FIPS

PUB 38 "user community". To accomplish this purpose, it is necessary that

negative opinions, unflattering examples of current practices, etc. - all be

freely expressed, without fear that such remarks might be traced to any

individual

Secondly, I've asked the panel members to lead off the session with

presentations. I would like to ask that no questions be initiated during

these presentations, since they are scheduled to last the entire "pre-lunch"

period. I hope, however, that you'll be able to save all your questions

until our "after-lunch" period, when I'll turn the floor over to the

audience

Let me begin by giving you some information about myself and the panel. I'm

currently with the Social Security Administration, where I'm responsible for

the data processing center, which services the statistical, administrative,

and management functions of SSA, We've begun to feel the impact of FIPS PUB

38 in my organization, and have already begun to extend parts of the

guidelines to cover our specific procedures. My association with FIPS PUB

38 and TG-14 goes back much further than that, however. In the mid-1960's,

I had the dubious honor of being one of the "guinea pigs" used by NAVCOSSACT

to try out the initial draft of their documentation standards. At that

time, I headed the Washington office of a software consulting firm which had

a contract with NAVCOSSACT. Although we had severe problems with this

standard, I was intrigued with the possible advantages (not only to

NAVCOSSACT, but also to the vendor) of such standards. Consequently, we put

a lot of effort into our comments on the standards, and worked closely with

the NAVOCCACT personnel on testing revisions. As time went on, and the

standards improved, my initial optimistic appraisal of the potential

benefits was confirmed, and 1 became an enthusiastic supporter of the

standards. As most of you know, these NAVCOSSACT standards became the basis

of NAVY-wide standards, which in turn became the basis of DOD-wide

standards, which in turn were the starting point of TG 14's efforts with

FIPS PUB 38.

This brings me to our first panel member. Bob Hegland. Mr. Hegland

represents the single thread of continuity through the entire evolution of

FIPS PUB 38, from the initial NAVCOSSACT standards. I met Bob back in the

mid-60's, and since then I've stayed abreast of the documentation standards

field through him. He was an active member of each of the intermediate

40
standards groups (NAVCOSSACT, NAVY, DoD) , and is a key member of TG-14. Bob

is still with NAVCOSSACT, in the documentation standards area.

Mr. Shirley Alger is a co-worker of mine at the Social Security

Administration. I've asked him to be a member of the panel because he

represents essentially the entire sum and total of the Social Security

Administration's experience with the implementation of FIPS PUB 38, at this

stage. He has been given the task of organizing the programming

documentation standards activities of the Office of Management and

Administration. He chose, I think properly, to attack this responsibility

with the aid of FIPS PUB 38, His experiences, so far, are valuable, in that

he has run into some of the difficulties all of us will encounter. Some of

the ways in which he is going about trying to solve these problems will be

instructive. Most important, there is at least a touch of the real world in

his experiences. They may prepare you for what will really happen when you

try to put these guidelines into the form of a standard to be used by your

or ganizat ion

.

Mr. Herb Bright is well known to anyone who has been involved with ADP

standardization. Herb has made many significant contributions to computing

in general, and I felt his broad range of experience would be useful to draw

upon. I especially asked Herb to join the panel because he comes from

outside the federal government. He's currently President of Computation

Planning, Incorporated, which is a private, software-oriented, consulting

firm, I think Herb's experiences in using various government documentation

standards will be of interest to anyone documenting software using the FIPS

PUB 38 Guidelines,

It is my view that the purpose of this session is to create a general

awareness of the problems associated with the implementation of the

guidelines, in the form of standards for individual agencies, departments,

etc. What I hope we can explore, in some depth, is the considerations which

management ought to be aware of before committing their organizations to the

guidelines. It is my personal feeling that it would be most detrimental for

management just to take the naive attitude that the existing guidelines can

be "adopted" as standards by simply issuing a memo to that effect. That

kind of approach will not only have the immediate effect of failure, but is

bound to have a longer term effect of convincing people that the concept of

documentation standards itself is faulty. If, in this session, we can meaningfully explore some of the more important of the management

considerations which should be part of the implementation of the FIPS PUB 38

Guidelines, I would feel that we have had a successful session, well worth

the time and effort of everyone involved.

In trying to shape this session toward that goal, we each have distinct

roles. I have the easiest role of all. As session chairman, it's my

responsibility merely to state the problem and to "oversee" the resultant

discussion, (I don't intend to be too rigorous about overseeing the

discussion - if the group's excitement and enthusiasm is so great that the

session gets out of hand, I think we would be achieving our original

purpose,) The panel members are here to start the discussions. Their

presentations are intended to explore, only partially, limited aspects of

the problem. In the open discussion period, I hope to have them serve as a target for your questions and as a foil for your opinions. You, the

audience, have the most important role, I expect you to lead the

d i s c u s s ion , cha 1 1 enge the views of the panel, explore unaddressed aspects,

recount relevant experiences, suggest alternatives, etc, I want to

emphasize that I will positively encourage alternate viewpoints, criticisms

of the guidelines, etc. There is a natural tendency in conferences such as this to have only the enthusiastic "boosters" do all the talking. The panel

and I are obviously biased in this direction - we wouldn't have been invited

here unless we weren't already associated with documentation standards, I'm

going to insure that we don't monopolize this discussion.

41
To start off the presentations, I've prepared a few slides which give my view of the important aspects of problems in the implementation of

documentation standards from the FTPS PUB 38 Guidelines. In the hope of

creating a common basis of discussion I have previously distributed these to

the panel members and asked them to at least consider them in drafting their

presentations. I also intend to return to these topics in my final

summarization at the conclusion of the session.

(Transcription of slides in lieu of text of remainder of presentation.)

42
SLIDE I

SCOPE

o IDENTIFY POTENTIAL PROBLEM AREAS

o EXPLORE INTERACTION WITH DOCUMENTATION GUIDELINES AT WORKING LEVEL:

- ARE THE GUIDELINES GENERAL ENOUGH IN SCOPE?

- ARE THE GUIDELINES TOO ABSTRACT TO APPLY IN PARTICULAR CASES?

- ARE THE GUIDELINES COMPREHENSIVE ENOUGH TO PRODUCE SATISFACTORY

DOCUMENTS?

- DO THE GUIDELINES PROVIDE A NATURAL INCENTIVE FOR ACCEPTANCE BY

ASSISTING THE "WORKERS" IN THEIR RESPONSIBILITIES?

o DISCUSS APPROACHES TO PARTICULAR PROBLEMS:

- ADAPTATION OF GUIDELINES TO PARTICULAR WORKING ENVIRONMENTS

- SYSTEMS, OPERATIONS, PROGRAMMER FAMILIARIZATION AND TRAINING

- ELIMINATION OF "PASSIVE RESISTANCE"

SLIDES II, III, IV, & V

DISCUSSION TOPIC "SEEDS"

o ARE THE GUIDELINES GENERAL ENOUGH IN SCOPE?

- DO THEY CAPTURE THE ESSENTIAL ELEMENTS OF SYSTEMS ENCOUNTERED

IN THE "REAL WORLD"?

- ARE THEY TOO BATCH-PROCESSING ORIENTED?

o ARE THE GUIDELINES TOO ABSTRACT TO APPLY IN PARTICULAR CASES?

- CAN WORKING LEVEL PERSONNEL RELATE THEIR INFORMATION INTERFACE

REQUIREMENTS TO THE CONTENT SPECIFIED IN THE GUIDELINES?

- SHOULD THEY BE REINTERPRETED, EXPANDED, MODIFIED TO MATCH LOCAL

ENVIRONMENT?

o ARE THE GUIDELINES COMPREHENSIVE ENOUGH?

- ARE ALL THE ELEMENTS OP A SYSTEM WHICH REQUIRE DOCUMENTATION

ADEQUATELY ADDRESSED?

- WILL DOCUMENTATION PREPARED IN ACCORDANCE WITH THE GUIDELINES

BE SATISFACTORY?

o DO THE GUIDELINES PROVIDE A NATURAL INCENTIVE FOR, ACCEPTANCE BY

ASSISTING THE "WORKERS" IN THEIR RESPONSIBILITIES?

- WHAT DO THE GUIDELINES DO FOR THE PROGRAMMERS, OPERATIONS,

SYSTEMS PERSONNEL?

- WHAT FAMILIARIZATION, TRAINING, ETC. IS NECESSARY?

43
PROBLEMS IN USING THE DOCUMENTATION GUIDELINE

Robert R. Hegland * Naval Command Systems Support Activity

(Code 70.3)

I . INTRODUCTION

The items that follow contain a discussion of some of the problem areas that

have been raised in the past regarding computer program documentation

standards and guidelines. Most of these problem areas can be resolved; some cannot* There are few standard-s or guidelines that are perfect and about

which no questions can be raised. The guidelines contained in FIPS PUB 38 are the product of not only the FIPS committee, but also of many other

committees and individuals who have worked with its predecessors. Each of

these committees raised questions and resolved them by changing and

enhancing the documentation system. A characteristic of a guideline such as FIPS PUB 38 is that it must be reviewed, updated, and changed as our experience grows.

II. AUTOMATED RUN INSTRUCTIONS

Some organizations now generate what they call Automated Run Instructions

from the run streams of their programs. They have asked if this removes the

need to produce an Operations Manual. It is, of course, up to the central

office or the implementing organization to review this question in detail

and determine whether all of the items of information in the Operations

Manual are covered by the Automated Run Instructions. My reaction is that

there are certainly some parts of the Operations Manual that can be replaced

by such run instructions. There are other parts, however, that are probably

not a part of the run instructions, such as the Program Inventory, some of

the information about the Output Reports, and information about Non-Routine

Operations and Remote Operations.

III. REAL-TIME, ON-LINE

Systems that perform real-time, on-line operations, and that may have a fully dedicated computer to run them, have always been a problem to document

in terms that users can understand, since the documentation must be

sequential, and the programs can run in different sequences. Whenever

possible, with these types of systems, it seems to be a good idea to build

as much tutorial information into them as possible. There doesn't seem to

be any all-encompassing solution to this problem for the User's Manual. The

Program Maintenance Manual can, of course, still be written as shown in the

Guideline, since it can be sequenced by program or module. The Operations

Manual would need to be quite different from that in the Guideline, since

there is very little operator intervention or action required in most of

these systems. Instead, the terminal operator, who is really a "user", has

significant control over what is largely operator functions in nonterminaloriented systems.

IV . STRUCTURED PROGRAMMING

The question has been raised in the past about whether this documentation

system can be used to support structured programming projects. The general

feeling on several committees is that there is no essential difference in

documenting structured programs and programs written using other techniques.

As a matter of fact, a large contractor looked at that problem with the DoD

version of the documentation standard, and had only a very few changes to

recommend. Most of these changes did not have a significant impact on the

DoD standard.

V. COBOL

The statement has often been made that COBOL is " s e 1 f -documen t ing " and the

question has been raised as to how this relates to the documentation

Guideline. COBOL is certainly written in English-like statements, and that

44
is a great aid for a programmer who is trying to determine what the program

is doing. With COBOL, there is still, however, a need to prepare a Program

Maintenance Manual (particularly for a large system), since a new programmer

still needs a narrative overview to use in becoming familiar with the basic

structure of the program system. There is no need, in the Program

Maintenance Manual of a COBOL program, to include a detailed narrative of

the logical flow of the program. COBOL is not, however, "self-documenting"

for a user to read or for a computer operator. Consequently, there is still

a need for written documents for these functions. Since COBOL is, to some extent, self-documenting, then if the program has been well commented, less

detail needs to be included in a written document on the program than would

be needed if the program were written in a less familiar language or in

machine language.

VI . PROGRAM MAINTENANCE MANUAL

There has been a proposal that the Program Maintenance Manual isn't really

needed, and that it should be replaced by the Program Specification, which

was written during development, and kept up to date as the programming

progressed. The Program Maintenance Manual, of course, serves several

purposes, such as to support the transfer of the system to another

organization, or in training new programmers in maintaining the system. The

approach of using the Program Specification as the Program Maintenance

Manual can be made to work, but there are some very real problems in doing

so. First, it means that a Program Specification would have to be written

during the development of each and every system. Using this approach also means the Program Specification would have to be updated constantly as the

system was developed. This updating seems to be difficult to do in the real

world. This, again, is something that a central office needs to look at

very carefully in implementing the Guideline,

VII , TERMINOLOGY

One of the continuing problems with this Guideline, and with all guidelines

standards, is that the terminology may mean different things to different

organizations. For example, a "system" means, to some people, the hardv/are

and software; to others, the term means the application system being

programmed. This Guideline has been written, as much as possible, using

basic ADP terms that have generally accepted meanings across all

organization lines. If input is received from a satellite, for example, it

is still input; the fact that it comes from a satellite won't be mentioned

in the Guideline, A related problem in all guidelines and standards is that

they must be written in English. Even though we have a standard Dictionary

for Information Processing, we still have to use English to communicate our thoughts and ideas, and English is an imprecise language that allows what

one person writes to be interpreted differently by another person. In using

the Guideline, authors should remember that it was written to cover as many

different organizations and situations as possible. It is necessarily

subject to interpretation. Authors should try to fit what is included in

the Guideline into their own environment.

VIII. CONCLUSION

Problems perceived in using the Guideline depend on how thoroughly it has

been reviewed and understood, both by the authors and the implementing

central office. Some problems are harder to resolve than others, but the

central office needs to anticipate as many problems and questions as possible, so that implementation guidelines can be promulgated at the same

time as the Guideline. Many of the problems that arise are those that have

already been addressed and discussed in Section 2 of FIPS PUB 38.

* The comments contained herein are the author's, and do not necessarily

represent policy of the Department of the Navy or of any naval activity.

45
SYNOPSIS OF QUESTIONS AND ANSWERS FROM PARALLEL SESSION B Robert A. Mattes & Social Security Administration

Kenneth Rodey

National Security Agency

Question : There appears to be a lack of guidelines to instruct individuals on how to

handle changes in the Maintenance Manual. Was this deliberate?

Panel Member : YeSj the guidelines were omitted intentionally, to allow each organization

the opportunity to develop its own administrative procedures for handling

changes to the Maintenance Manual. It was assumed that each organization

handles the posting of changes differently (e.g., change pages, complete

r ewr i t e , etc.).

Panel Member : Because of the large investment in Application Programming, there is a definite need for a reliable access audit-trail, to protect programs from

being modified without maintaining a documented record of those

modifications. However, there is currently very little attention being paid

to this matter. In general, subtle changes to computer programs are not

backed up by Audit Trail Documentation. Because of this, existing Program

Documentation seldom reflects the true nature of the program that it

describes

Panel Member : The Social Security Administration has a Customer Billing System that

maintains a log of what systems are being used and by whom.

Panel Conclusion : The Maintenance Manual lends itself possibly to assist in assuring that

changes are properly documented. It also assists in exploring the

ramifications of a pending modification. However, without rigid procedures

on posting all changes to it, the Maintenance Manual would soon become

obsolete.

Base Documentation, a list of

ase, and what fields they

Panel Member : There is currently provision for the identification of all software

(computer programs) which access the Data Base (see section 2.2 of the Data

Base Specification). As can be seen, this provision does not identify which

programs access which fields. This identification could be handled by

section 3.C of the Data Base Specification, when describing the Logical

Characteristics of Fields. However, the maintenance of such a cross reference list should be handled through an automated system rather than a manual system. FIPS Task Group 17 is now developing guidelines for Data

Resource Directories, which will address the issue of relationships between

data and the processes which work upon it.

Question : Is there a provision to include, in the Data

what programs are allowed to access the data b access?

Ques t ion : Of the 10 documents, how many should be used to retrofit existing programs?

Is it practical to retrofit documentation of on-going programs?

Panel Member : There is no general rule for determining which documents should be used, or the level of detail to be recorded for each. This is determined by the

needs of the individual organization. It is advisable that an organization

consider each existing program, independent of all others, when determining

the amount of documentation to capture. Because of basic differences among

programs (e.g., o n e- t ime - s ho t , large size, frequently used, no longer in

46
operation, volatile coding changes, etc.), some programs will require more documentation than others.

Panel Member : High level management at SSA decided to rewrite its payroll system, rather

than produce the necessary documentation for an existing system.

Panel Member : Every organization will most likely encounter considerable resistance from

analysts and programmers concerning the retrofit of documentation for

existing programs.

Panel Member : Typically, management does not know what they want. Good documentation is

the physical evidence of what they require.

Panel Member : Third generation equipment eliminates the need for some of the manually

produced documentation previously prepared (e.g., Operations and User's

Manu a 1 s ) . Pane 1 Member : The burden of documentation is a problem for internal ADP management,

whereas user management is unaware that a problem concerning documentation

exists . Panel Member : User management is often insensitive to the need for documentation, and,

typically, does not clearly spell out the application problem, or what their

ADP requirements actually are. Question : How do you convince the interactive on-line user to read and follow the

User's Manual?

Panel Member : Typically, the interactive on-line user will not read documentation that

exceeds one page in length. Therefore, this necessitates having the user documentation on-line and readily available to the user in a s e 1 f - t each ing

mode (e.g., HELP modules).

Ques t ion : Isn't FTPS PUB 38, especially the User's Manual, directed toward second

generation computer systems?

Panel Member : Many parts of FIPS PUB 38 are oriented to, or thought of as being second

generation. In fact, FIPS PUB 38 has its historical origin in the mid1960's, when second generation equipment was in prominence.

Panel Member : It is very difficult to prepare a standard or guideline that would be

applicable to all on-line interactive systems having various levels of

sophistication. Special purpose manuals that support the particular on-line

system should be prepared in hardcopy or softcopy form to supplement the

User's Manual. For on-line systems, the User's Manual could satisfy the

documentation needs of top level management of the user organization.

Question : Have you experienced any difficulties with the Data Requirements Document as

it applies to on-line systems?

Panel Member : No, because the Data Requirements Document is developed around requirements,

not programs or hardware.

Question : Who is the author of these documentation manuals, the programmer or the

analyst?

47
Panel Member : Depending upon the environment of the organization, either programmer or analyst could be the author.

Audience Comment : Some companies have quality assurance groups that employ writer/editors to

confer with the programmer/analyst and actually prepare the documentation

for the program/ system. The assumption is made that if programmers cannot

explain the system to an editor well enough, then the editor cannot document

it. In addition:

1, The editor is a better writer.

2, Analysts can devote their time to Systems Analysis and Design.

3, Programmers can devote their time to programming,

4, The entire operation is more cost-effective.

5, Having to explain processes to a third party leads to better

design through structured thinking.

Quest ion : How would software contractors react to the inclusion of a standard

documentation like FIPS PUB 38 as part of the deliverables under a software

contr ac t

Panel Member ; Pips pub 38 would be acceptable for second generation type equipment, but

the contract would have to be explicit about which documents, and which

items within them, should be included, and how they relate to the system

being developed.

Que s t ion : Would FIPS PUB 38 be applicable to small dedicated mini-computer systems?

Panel Member : Absolutely, since dedicated, departmental, mini-computer-based systems

typically resemble late first generation or early second generation computer

systems, for which FIPS PUB 38 is ideally suited.

Que s t ion ; FIPS PUB 38 attempts to define what is minimum documentation. Has the

Social Security Administration established what they feel is too much

documentation for different circumstances?

Panel Member : SSA has not established any general guidelines, to be followed by those who

develop systems, on what is too much and what is too little. However, we are attempting to determine documentation requirements by requesting our four applications divisions to gather all available documentation together,

and to compare it to FIPS PUB 38. Then we ask them to comment on the ten

document types as being C-Complete, I-Incomplete , or NA-Not Applicable,

Quest ion : Does the Program Maintenance Manual present an overall, detailed picture of

the System for the analyst, who has to determine what ramifications a given

change will have on the entire system?

Panel Member , No, because the Program Maintenance Manual is intended to present a detailed

description of a given program; not the entire system. Perhaps, if the

functional requirements document and the system/ subsystem specification

were kept up-to-date, they could be used to determine the impacts of

changes

Panel Member : A cross-reference grid showing the relationships between programs and data

element s/ items could be prepared to supplement the Program Maintenance,

48
Ques t ion : Does anyone prepare and maintain their documentation using interactive text

editing systems?

Panel Member : Yes, SSA currently does some, and will be receiving additional equipment to

expand this effort.

Ques t ion ; There appears to be a lack of und

contents of FIPS PUB 38. What do

should information be described?

Panel Member : The first two documents that are created in an organization are hard to

produce, and require a great learning process. Each organization will have

to develop its own interpretation of the content of each document, and the

degree of detail to be described for each.

Ques tion : The contents of similar sections of many of the documents seem to capture

redundant information (e.g., Operating Environment is specified in both the

Functional Requirements Document and the System/Subsystem Specification),

Was this deliberate?

erstanding, or a misinterpretation, of the

"paragraphs" mean, and to what extent

Panel Member : Yes, information has been included in each document to provide a "standalone" understanding of the document, with a minimum need for cross- referencing to parts of other documents that may have been produced.

However, it would be perfectly valid to set up the documentation

requirements in your organization so that information is captured only once

in a specific document, or once in a specific section of the overall

documentation which your organization records for a given Automated Data

Sys tem

.

Panel Member : Each organization would have to develop guidelines and examples to follow in

the preparation of documentation. FIPS PUB 38 was not intended to be a stand-alone document.

SUMMARY

1. Are the guidelines general enough in scope? No, to a large extent they

are obsolete, since the batch orientation is much too strong and real time,

on-line systems are not adequately addressed.

2. In terms of the abstraction of the documentation standard, there is a good deal of ambiguity, and a need for interpretation at the lower levels.

FIPS PUB 38 should not be issued without internal guidelines, or else its

implementation would be left up to each individual.

3. Are guidelines comprehensive enough? It provides for adequate

documentation in those situations for which it was intended, but there is some question about its maintainability.

4. What kind of familiarization training and division of responsibility is

best for doing documentation? It appears that using a documentation

specialist or tech writer, who is not a programmer or systems analyst, may

be the best way to go for quality documentation.

5. The areas of System Level Maintenance Manual needs to be addressed^

along with the tools for se 1 f -document ing on-line query systems.

49
INTRODUCTION: "STANDARDS, TRAINING, POLICY, AND AUDIT PERSONNEL"

Harris G. Reiche

Director, Office of ADP and Telecommunications Management

Department of the Interior

Welcome to Session C. Now that there is a FIPS PUB 38, what do you do with

it? We will be addressing that question from the standpoint of agency staff

function. More specifically, for you who are the agency standards managers,

or responsible for agency ADP policy, do you turn the guideline into a standard? Do you use it only as a guideline? Do you leave that decision to

your bureau or other subordinate organizations? Or even to operational

management for your decentralized programming functions? How do you handle

training throughout your agency? Whatever your decision is with respect to

the foregoing questions, how do you maintain follow-up to assure good

doc um entation?

How should the auditing staff use FIPS PUB 38? How important is use of the

guidelines to the success of application programs in meeting their

objectives? How can the auditor improve his performance by using the

guideline? Of course there is no single answer to any of these questions.

It is unlikely that we could even get agreement among the panel members. It

isn't the intention of this panel to develop a canned approach to

implementing FIPS PUB 38, but to stimulate a discussion of the issues--to

exchange the approaches being taken by various agencies.

The format of the session will include presentations from three panel

members, followed by a discussion among the panel members and the audience.

The first panel member, Mike Gall, from the Civil Service Commission, will

address some of these issues from the perspective of a relatively small

government agency —where, to a great extent, the ADP line and staff

organization is the same.

The second panel member is Joe Strnad, from the Department of Health,

Education, and Welfare, He will discuss the issues from the perspective of

a large agency, with large, and often times autonomous subordinate

organizat ions

The third panel member, Phil Morrison, is from the Department of Housing and

Urban Development. He will review FIPS PUB 38 from the auditor's

perspective.

The fourth panel member, Roy Young, from Health, Education, and Welfare, was

a member of Task Group 14, which developed FIPS PUB 38. He will participate

in the discussions following the three presentations.

50
FIPS PUB 38 - - IMPLEMENTATION PHILOSOPHY IN THE DEPARTMENT OF HEALTH,

EDUCATION AND WELFARE

Joseph J. Strnad

Department of Health, Education and Welfare

Office of Management Technology

200 Independence Avenue, S.W,

Washington, D. C. 20201

Before addressing the questions specified for discussion by this panel, I will first cover the uses being made of FIPS PUB 38 at the present time in

this Department; and then discuss how we propose to integrate the

documentation concepts contained in the publication into our ADP operations.

Hopefully, this will explain our concept of how staff persons, such as assembled here today, can directly influence the documentation process in

their departments, in a manner consistent with overall management

objectives.

As most of you know, HEW consists of several components, with distinctive

missions and varied historical backgrounds. We have organizations that have

been around for a long time, such as the Social Security Administration

(SSA), the Public Health Service (PHS), and the Office of Education (OE);

and relatively new organizations like the Office of Civil Rights (OCR) and

the Office of Human Development (OHD). Needless to say, the older

organizations have established documentation practices set forth in systems

manuals and standards. Depending upon the quality of such manuals, these

agencies are finding FIPS PUB 38 useful in different ways. For example, the

Bureau of Data Processing of SSA is revising their operations manual, using

FIPS PUB 38 as a guide. The PHS is developing a standards manual, based on FIPS PUB 38, for use by their various component agencies. OE , on the other

hand, published their ADP systems manual in September, 1975, which had a chapter on documentation which is very similar to FIPS PUB 38, since it was partly based on the ANSI publication "Technical Documentation of Computer

Projects". Our newer organizations, like OHD, have no documentation

manuals, and have found FIPS PUB 38 useful in specifying requirements to

contractors for new systems development efforts.

When FIPS PUB 38 was issued in February, 1976, we at the department level

recognized that it would have value in varying ways among our componen t s , gnd

experience to date has confirmed that belief. We gave the publication broad

distribution in the department - around 800 copies, but recognized that it

would take a long time to realize any appreciable impact, A principal

reason for not mandating its use was the simple fact that revision of

documentation manuals and guides requires resources which may not be

available in the agencies' budgets. Also, agencies have their own priorities, and may have requirements that rank above a major overhaul of

documentation practices, particularly if they already have a manual or established practices which they consider reasonably satisfactory. In

short, we in HEW distributed FIPS PUB 38 as a guideline, to be used as deemed appropriate by its recipients.

However, we did not let the matter rest there. We at the department level

recognized the need to assure that all components in the department should

strive toward a level of documentation to achieve the goal of FIPS PUB 38 - namely "to provide information to suppport the effective management of ADP resources and to facilitate the interchange of information".

Last spring, we launched an overall ADP systems management study project

designed to lead to departmental policy regarding life cycle system

management, from the planning and budgeting phase through the operations

phase. Areas under study are: systems categories, approval levels,

monitoring, operational reviews, as well as system documentation within the

51
software life cycle. While our initial concepts on documentation do not

exactly coincide with FIPS PUB 38, we have found it a useful guide in our deliberations. In a few weeks, we will be convening a departmental task

force to review the various comments we have received from our components,

and to finalize our life cycle systems management concepts and policie*. It

is our objective to establish, within those policies, the requirements for

documentation related to departmental AD? management. Again, this is a long-term proposition, but we feel it holds promise of bringing all

components into some degree of harmony regarding system documentation. It

is very doubtful, in an organization as large as HEW, that we will ever achieve uniform documentation throughout — but we should strive for basic

similarity, with minimum standard requirements, to facilitate exchange and

use of data and systems. FIPS PUB 38 provides a common benchmark for this

to occur throughout the federal establishment.

In the near term, I think the philosophy underlying the standard can be

promulgated in two or three different ways;

First, I think the FIPS PUB 38 should be required reading by all

professionals in the ADP business. Every professional should be familiar

with the family of documents in the publication and the suggested content

and structuring of the documentation.

Second, FIPS PUB 38 should be required reading at the level within

organizations where the responsibility rests for maintaining in-house ADP

procedures, including documentation. It should be maintained as a ready

reference. If the organization's systems manual is under revision, and the use of FIPS PUB 38 guidance is a feasible alternative, it should be

followed. By this means, we can gradually evolve toward a uniform standard

for documentation.

Lastly, managers of programs responsible for approving new system

development efforts should have a general awareness of the documentation

appropriate for various phases in the software life cycle. This will tend

to make them more prone to support the resource requirement, and also, it

will give them some idea where answers can be found to their system

questions. We in HEW feel strongly that program managers being supported by

ADP systems, if they are to get their money's worth from the resources they

are investing in systems, must develop an awareness of ADP systems and what

makes them tick. FIPS PUB 38 is a good primer for this purpose.

We in HEW, as a corollary feature of life cycle management, plan to conduct

review and evaluation of selected systems. In addition to evaluating system

performance against requirements, we intend to inspect the adequacy of

system documentation to support the system, as another measure of system

performance. We would expect to find documentation that approaches the FIPS

PUB 38 specifications, or something reasonably adequate, in lieu thereof.

Accordingly, FIPS PUB 38 will serve as a basic checklist in this review and

evaluation undertaking.

To summarize, we in HEW have not legislated across-the-board-compliance with

FIPS PUB 38, but are making some progress toward its goal of better overall

documentation of computer programs and automated systems.

52
THE ROLE OF AUDITORS IN THE DEVELOPMENT AND EVALUATION OF AUTOMATED SYSTEMS

Phillip L. Morrison

Office of Inspector General

Department of Housing and Urban Development

Office of Audit

451 7th Street, SW — Room 8284

Washington, D. C. 20410

Si. ce most of you are not auditors, I would like to start by defining the

role of auditors, both internal and external, in the development and

evaluation of computer programs and automated systems. Then, I will address

the effect documentation has on auditors, and comment on the impact I expect

FIPS PUB 38 to have on auditors.

For the purpose of this discussion, I will define internal and external

audit very narrowly. I define external audit as an audit group independent

of the Department or Agency, Since we are dealing with the Federal

Government, most external auditing is performed by the General Accounting

Office. I define internal audit as an audit group within the Department or Agency, but independent of the part of the organization responsible for the

development of computer programs and automated systems,

I realize that most of the technical audits of computer programs and

automated data systems are performed by audit groups within data processing

organizations. I do not mean to discourage or belittle this approach, but

it is part of the development process, not a totally independent review or analysis, and my talk addresses independent audits.

Since I spent almost ten years with the General Accounting Office (GAO)

before joining HUD, I think that I can give a fair explanation of the role

of GAO. As you know, we expected to have Dr. Carl Palmer, who is currently

with GAO, here with us today.

General Accounting Office

GAO has been active in the area of ADP for many years, Mr. Puckorius has

already mentioned GAO ' s involvement, and you will find a reference to the

1974 GAO Report on Documentation on the inside cover of FIPS PUB 38. I have

that report, and several other GAO reports, pamphlets, and guides dealing

with ADP for any of you that may want to look at them.

One of the GAO publications that I brought is titled "STANDARDS FOR AUDIT OF

GOVERNMENTAL ORGANIZATIONS, PROGRAMS, ACTIVITIES & FUNCTIONS." This

pamphlet prescribes the standards applicable to both internal and external

audits of the Government. A basic premise of these standards is that "the

term audit is used to describe not only work done by accountants in

examining financial reports, but also work done in reviewing (a) compliance

with applicable laws and regulations, (b) efficiency and economy of

operations, and (c) effectiveness in achieving program results."

Another is an exposure draft, which GAO is currently circulating for

comments, "GUIDE FOR RELIABILITY ASSESSMENT OF CONTROLS IN COMPUTERIZED

SYSTEMS (FINANCIAL STATEMENT AUDITS)." This draft is essentially a questionnaire, which provides auditors with a rapid, but crude, evaluation

of internal controls.

I believe that a great deal of the confusion concerning the role of auditors

is due to the fact that GAO has two roles. While GAO is primarily an auditing organization, it also has the responsibility to prescribe the

principles and standards of accounting for the Federal Government, and to

approve the accounting systems used by Federal Departments and Agencies.

The GAO Manual for the Guidance of Federal Agencies prescribes both

53
accounting requirements and the procedures necessary to obtain approval of

an accounting system. The manual outlines some minimal documentation

requirements for automated accounting systems, and refers to separate review

guides which GAO uses in the approval process.

GAO has issued three review guides which agencies must complete and submit

with requests for approval of accounting systems. These review guides cover

the following areas:

ACCOUNTING SYSTEMS DESIGN

ACCOUNTING SYSTEMS DESIGN; ADP APPLICATIONS

PAYROLL SYSTEMS DESIGN

The review guides are, essentially, questionnaires which deal with internal

controls and audit trails. An agency must answer specific questions

identifying the controls in an automated system, and provide specific

references to the documentation of the controls. I have copies of these

questionnaires available, if any of you care to review them.

GAO approval of accounting systems is based entirely on documentation, and

the review guides are used in lieu of imposing documentation standards. GAO

encourages agencies to use the review guides during the design and

development of automated systems that require approval. But, GAO does not

start reviewing a system until the agency submits the documentation and

review guides, and requests a review. This GAO review is strictly for

approval purposes, and will not result in an audit report.

Most of you are probably familiar with GAO because of GAO's auditing. Since

GAO auditors require compliance with the principles and standards of

accounting prescribed by GAO, I can understand the common view that auditors

require the inclusion of internal controls and audit trails. The

distinction that I would like you to understand is that GAO does not

prescribe principles and standards of accounting as part of its auditing

role.

Internal Auditors

Internal audit organizations do not have a responsibility to prescribe

principles and standards of accounting — consequently, they do not normally

prescribe any requirements for either documentation or internal controls.

When internal auditors review an automated system, the primary goal is,

usually, to determine if the system is performing its function accurately.

This determination requires an analysis of the internal controls in the

system, and controls are identified by reviewing documentation, the subject

of FIP$ PUB 38. A review of internal controls requires two separate

determinations: (1) Did the user identify the controls necessary to comply

with applicable statutes, regulations and policies? (2) Did the ADP staff

implement all of the requirements specified by the user, and all controls

necessary for accurate functioning of any automated system?

If you think that you are adding controls to automated systems for auditors,

you should review the purpose of the controls. The user should be far more interested in the accuracy of any automated system than the auditors. After

all, auditors may look at a system occasionally or periodically, but users rely on it every day to get their job done. Users and developers must share

the responsibility for the development of accurate automated systems.

Auditors also have a responsibility in this area, but the audit

responsibility is secondary, and it in no way diminishes the primary

responsibility of the users and developers.

Ideally, internal auditors should be involved early in the development of

automated systems. Mr. Puckorius stressed this in his presentation. This

approach would minimize the impact of any problems auditors identify.

Unfortunately, early involvement is easier said than done. Those of you who

54
are auditors are aware of the difficulty involved in trying to review a system during the development process. Unless documentation is complete and

current, and designed to identify internal controls, an audit of this type

will require a lot of audit resources, and produce no visible product. The

easy alternative for the auditors is to let the review slip until the system

is developed. Then the auditors can look at finished documentation, review

the GAO questionnaires, if required, and analyze the acceptance testing

performed by or for the user. The auditor can use a test deck to check the

functioning of the program, and he can issue a deficiency report on any

problems — a product to show for his work.

The users and/or developers of automated systems could help internal

auditors to review systems while they are being developed. Both of these

groups know that it is easier, faster, and less expensive to design a system

right in the first place, rather than to patch an operational system to make

it accomplish something it was supposed to do in the first place. But, why

invite trouble? How many of us would go out of our way to invite a critical

evaluation of our work? Besides, the people responsible for developing

systems frequently believe that auditors will place additional requirements

on them, particularly in the area of internal controls. If so, it is only

because others did not do their job right.

GAO and 0MB have both taken a very active role in encouraging internal audit

groups to evaluate automated systems while they are being developed. Two

recent GAO REPORTS, one dealing with crimes in computer based systems, and

the other dealing with automated decision making systems, included

recommendations for internal auditors to be involved in the design, testing

and operation of automated systems. Many agencies made commitments to the

Congress, in response to these recommendations, and 0MB required all

agencies to address these recommendations in their FY 1978 budget

submissions. The Privacy Act has placed new requirements on automated

systems, and both developers «nd auditors are currently evaluating their

responsibilities under this act. I think it is safe to say that every audit

group in the Government has either already started to get involved in the

development of automated systems, or is making plans to do so. Effects of Documentation

Poor documentation can be compared to a blindfold; this comparison is valid

for both existing systems and systems under development. Poor documentation

will increase the time required to perform an audit, and decrease the

effectiveness of the audit.

Poor documentation will conceal some of the deficiencies in a bad system, at

least for a time but, it will also hamper any efforts to correct

deficiencies that do surface.

Good documentation is an invitation for critical analysis. If the

documentation is good enough, errors will stand out like a sore thumb. But,

good documentation will help the developer avoid errors and simplify the

correction of errors. Auditors can make a meaningful contribution to the development of automated

systems, but only if documentation is kept current, and internal controls

and audit trails are addressed adequately. Otherwise, effective audits will

be feasible only after the system becomes operational. Internal audit

groups are just developing the ability to review automated systems. We face

real problems allocating the time of the few people who are qualified to

perform this work. Unless users and developers work with us, we will be

forced to delay our reviews until after the systems are implemented. This

approach will let us review more systems with less resources, but it means modifying existing systems to make them do the things they should have been

designed to do. As long as this continues, we will always be fighting brush

fires not an efficient or cost-effective approach for anyone.

55
I have tried to show that auditors are vitally interested in both

documentation and FIPS PUB 38. But, the impact is indirect, since auditors

do not prepare documentation or prescribe system requirements. We use documentation, and any improvement in documentation will help auditors. I believe FIPS PUB 38 will cause a big improvement in the documentation of

automated systems. The documentation required by FIPS PUB 38 does not meet

all the needs of auditors, but it comes closer to meeting these needs than

any documentation standards that I have seen in any Federal Department,

outside of DoD. I hope to work with HUD's standards staff in the

implementation of these guidelines, and any time our auditors review a computer program or automated system we will use and evaluate the related

documentation.

The documentation guidelines in this publication may meet the needs of the users and the computer professionals, but I do not think they will replace

the GAO review guides. As an auditor, I would like to see the area of

controls addressed separately, to assure a systematic treatment of this

important area. Auditors realize that controls cost money, and the

inclusion of any redundant or unnecessary controls is a waste of money. Our

goal is to include the minimum number of controls necessary to achieve the

required accuracy. The GAO review guides were prepared for accounting

systems, where every effort must be made to avoid any errors. We recognize

that this degree of accuracy is not required in all automated systems, but

it is very disturbing to find that most systems are developed without a systematic approach to controls. I would like to see a systematic approach

to controlling all input, processing and output; this would insure the

placement of controls as early in the system as possible, and the avoidance

of redundant controls.

My final comment on FIPS PUB 38 may not be a fair criticism, but I consider

it to be a problem that these guidelines! address only the automated portion

of any function. When auditors review an area, they try to look at the

entire operation from beginning to end, not just the automated portion. I would like to see documentation that includes an entire function, including

everything that takes place before and after the automated portion.

56
SYNOPSIS OF QUESTIONS AND ANSWERS FROM PARALLEL SESSION C Fred J. Cole

Public Health Service

Edie Lasner

Office of Education

Ques tion : How does one train people to document? Will Civil Service offer a course?

Young : Training is a product of what each agency/person expects. FIPS PUB 38 does

not address training. FIPS Task Group 14 has talked about having some sort

of training, but nothing is planned now. While the Civil Service Commission

has classes on documentation, they are not necessarily concerned with FIPS

PUB 38.

Strnad : Documentation will be prepared, with or without training, and managers must

support it. Documentation has been with the ADP community since day one, so

its actual needs and/or potential needs to management are well established.

Ques t ion : Will OMB enforce FIPS PUB 38 as standard (i.e. not a guideline)?

Reiche

:

No. FIPS PUB 38 addresses all levels of document actions and therefore can

be utilized as an outline of the requirements. Local management must

determine the degree that FIPS PUB 38 affects any particular application.

This was the logic in making it a guideline, not a standard.

Audience Comment : Whether one uses "Standards" or "Guidelines" depends on the diversity of

computer applications.

Que 8 t ion : Wi 1 1 TG 14 assist agencies in implementing FIPS PUB 38? Are examples of

documentation and forms going to be made available as guidelines?

Young : TG 14 has no specific plans for such assistance. Examples of documentation

and forms are not going to be made available. However, NASA and GSA, among

others, have examples of documentation and forms which conform to the

guidelines in FIPS PUB 38.

Ques tion : How does one "force" non-ADP professionals (e.g. mathematicians) to use FIPS

PUB 38?

Cole : Show such people how documentation is beneficial to them.

Gall : Enforcement is possible only in the area of security compliance

people are "on their own hook."

Otherwise

Question : Who within an organization is responsible for: (1) determining the scope of

documentation, and (2) compiling the documentation?

Gall :

( 1 ) The project team leader in the f unc t iona

1

area, i.e., a person not in

the ADP standards area, but one who follows standards developed by the

standards area. This is so whether the agency is small or large; the

participation of management will depend on the complexity and size of the

project. (2) The systems analyst. Some agencies have gone so far as to

hire technical writers to develop the documentation required for a given

sys tem

.

57
S trnad ; Where there are contractors, the contracts must specify the level and

complexity of documentation.

Quest ion : How, at the Civil Service Commission, did you get project leaders in the

functional areas to take over documentation? At GPO, ADP is always taking

back the function.

Gall ; Adequate resources are provided in the functional areas. ADP does provide

documentation guidelines and help.

Question:

What did Mr. Morrison mean by "controls" in non- f inane ia 1 systems? Are you

referring to normal edit criteria, physical controls, or what?

Morr ison : The user should know his real needs, what is an acceptable product to him.

Gal 1 : For instance, the CSC Recruiting and Examining System has 3 million

potential applicants on-line to 60 offices. System requirements specified

certain privacy constraints. Auditors reviewed the system design to

determine if it meets the users' requirements. Where possible, auditors are

in on the development of the design specifications.

Re iche : Auditors are concerned not just with financial management systems. Now, for

example, controls are concerned with privacy.

Audience Comment : Auditors should be looking at technical aspects of systems during

development. They should be looking beyond any financial and security

controls.

Audience Comment : Auditors see themselves as providing feedback to management. Management

areas looked at by auditors:

. Try to determine feasibility of the system.

. What are the objectives and how will they be met?

. Are they documented?

. Have you considered alternatives, or were you locked in?

. Have you thought about maintenance?

Technical areas looked at:

. Are there input/output controls and edit criteria?

. What is/will be the impact of the system?

. If the system goes sour, will the department be embarrassed?

. What are the risks involved?

. Security.

My Department audits only about 5% of its ADP systems.

Much discussion followed on who should have the audit function (ADP or general auditors); also, on whether auditors should have ADP training. The

session ended with the following (typical) question:

Ques t ion : Why was the requirement for record counts put in the user area, not ADP

operations?

Young : The argument goes both ways, but the "new school" puts such control checks

in the user area. Gall : Quality control is turned back to the user.

58
FIPS TASK GROUP 14 MEMBERSHIP

FIPS Task Group 14 (Documentation for Information Processing Systems)

prepared FIPS PUB 38 from existing guidelines, standards, and practices in

Federal agencies and other institutions. The following members of FIPS TG

14 (past and present) contributed to its development and publication.

Ruth Anderson, National Bureau of Standards

Fred J. Cole, Public Health Service

Phillip Diamond, Veterans Administration

C. L. Eadie, General Services Administration

Elizabeth Fong, National Bureau of Standards

James Gillespie (Task Group Chairman), Department of the Navy

D. H. Gridley, NASA Goddard Space Flight Center

Robert R. Hegland, NAVCOSSACT

Helena Hood, General Services Administration

Mitchell Krasny, National Technical Information Service

Tom Kurihara, Department of Agriculture

Edie Lasner, Office of Education

Beatrice Marron, National Bureau of Standards

Robert A. Mattes, Social Security Administration

Carl Palmer, General Accounting Office

Kenneth Rodey, National Security Agency

G. Joyce Rosencranz, National Security Agency

Mark Silverman, U. S. Geological Survey

Roy A. Young, Department of Health, Education and Welfare

SYMPOSIUM PLANNING COMMITTEE

The following people were responsible for the planning and organization of

the Symposium for Documentation of Computer Programs and Automated Data

Systems. Their plans were turned into reality by the people at NBS and CSC

who earn their living by doing this sort of thing.

Mark Silverman (Chairman) U.S. Geological Survey

Roy A. Young, U.S. Department of Health, Education & Welfare

Mitchell A. Krasny, National Technical Information Service

Beatrice Marron, National Bureau of Standards

Fred Rao, U;S. Civil Service Commission

59
NBS-114A (REV. 7-73)

U.S. DEPT. OF COMM. BIBLIOGRAPHIC DATA

SHEET

1. PUBLICATION OR REPORT NO. NBS SP-500-15

2. Gov't Accession

No.

3. Recipient's Accession No.

4. TITLE AND SUBTITLE

CCMPUTSR SCIENCE & TECHNOLOGY:

i;ocurnenti3.x>ion oi ooinpuX'er rrograms ana. AUXiOinauecL Liax-a oysi>6nis

Proceedings of a Symposium Held at the National Bureau of

Standards, Gaithersburg, MD, October 12, 1976

5. Publication Date July 1977

6. Performing Organization Code

7. AUTHOR(S)

Edited by Mitchell A. Krasny

8. Performing Organ. Report No.

9. PERFORMING ORGANIZATION NAME AND ADDRESS

NATIONAL BUREAU OF STANDARDS

DEPARTMENT OF COMMERCE

WASHINGTON, D.C. 20234

10. Project/Task/Work Unit No.

1 1. Contract/Grant No.

12. Sponsoring Organization Name and Complete Address (Street, City, State, ZIP)

Federal Information Processing Standards Task Group 14

(Documentation for Information Processing Systems) , National

Bureau of Standards, U. S. Department of Commerce,

Washington, DC 20234

13. Type of Report & Period Covered

Final

14. Sponsoring Agency Code

15. SUPPLEMENTARY NOTES

In conjunction with the ADP Management Center, U.S. Civil Service Commission,

Washington, DC 20415 . Library of Congress Catalog Card Number: 77-608169

16. ABSTRACT (A 200-word or less factual summary of most sigfxilicant information. If document includes a significant

bibliography or literature survey, mention it here.) This symposium was organized to introduce the Government ADP-community to the

concepts of when and how to apply the government-wide guidelines of FIPS PUB 38

"Guidelines for Documentation of Computer Programs and Automated Data Systems" - in developing both agency standards and operational documentation. The proceedings

contain all of the papers presented in the plenary session, and the papers plus

summaries of question and answer sessions presented in three parallel sessions for

management, operations, and staff attendees.

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)

Automated data systems; computer programs; documentation; documentation

content guidelines ; FIPS guidelines; software , symposium proceedings.

18. AVAILABILITY Unlimited

1 1 For Official Distribution. Do Not Release to NTIS

1 Order From Sup. of Doc, U.S. Government Printing Office Washington. D.C. 20402. SD Cat. No. C13. 1 Oi 'iOO-l

1 ! Order From National Technical Information Service (NTIS)

Springfield, Virginia 22151

19. SECURITY CLASS

(THIS REPORT)

UNCL ASSIFIED

21. NO. OF PAGES

66

20. SECURITY CLASS

(THIS PAGE)

UNCLASSIFIED

22. Price$2.10

USCOMM-DC 29042-P'7 tS-U.S. government printing OFFICE: 2 4 0- 8 48 /2 60
ANNOUNCEMENT OF NEW PUBLICATIONS ON

COMPUTER SCIENCE & TECHNOLOGY

Superintendent of Documents,

Government Printing Office,

Washington, D. C. 20402

Dear Sir:

Please add my name to the announcement list of new publications to be issued in the series: National Bureau of Standards Special Publication 500-.

Name

Company

Address

City State Zip Code

(Notification key N-503)

NBS TECHNICAL PUBLICATIONS

PERIODICALS JOURNAL OF RESEARCH reports National Bureau

of Standards research and development in physics,

mathematics, and chemistry. It is published in two

sections, available separately:

• Physics and Chemistry (Section A)

Papers of interest primarily to scier* ^."^ orking in these fields. This section covers a br .ige of physical and chemical research, wit'' jr emphasis on

standards of physical measy ^

, fundamental constants, and properties of m^

^'.asued six times a year. Annual subscription: D' c, $17.00; Foreign, $21.25. • Mathematical Sci-- ^,^<>.<> ^Section B)

Studies and com-- ^* .is designed mainly for the mathematician anH .Q<^*<;tical physicist. Topics in mathematical statis^^^c;^^^.leory of experiment design, numerical

analysi' >JP jretical physics and chemistry, logical de- sign ^ programming of computers and computer sys- t'-^X^jnort numerical tables. Issued quarterly. Annual

si^ ocription: Domestic, $9.00; Foreign, $11.25.

DIMENSIONS/NBS (formerly Technical News Bulletin) —This monthly magazine is published to inform

scientists, engineers, businessmen, industry, teachers,

students, and consumers of the latest advances in science and technology, with primary emphasis on the work at NBS. The magazine highlights and reviews

such issues as energy research, fire protection, building

technology, metric conversion, pollution abatement,

health and safety, and consumer product performance.

In addition, it reports the results of Bureau programs

in measurement standards and techniques, properties of matter and materials, engineering standards and services, instrumentation, and automatic data processing.

Annual subscription: Domestic, $12.50; Foreign, .$15.65.

NONPERIODICALS

Monographs—Major contributions to the technical liter- ature on various subjects related to the Bureau's scientific and technical activities. Handbooks—Recommended codes of engineering and

industrial practice (including safety codes) developed

in cooperation with interested industries, professional

organizations, and regulatory bodies. Special Publications—Include proceedings of conferences sponsored by NBS, NBS annual reports, and other

special publications appropriate to this grouping such

as wall charts, pocket cards, and bibliographies.

Applied Mathematics Series—Mathematical tables, manuals, and studies of special interest to physicists, engineers, chemists, biologists, mathematicians, computer programmers, and others engaged in scientific and technical work.

National Standard Reference Data Series—Provides

quantitative data on the physical and chemical properties of materials, compiled from the world's literature and critically evaluated. Developed under a world-wide

program coordinated by NBS. Program under authority

of National Standard Data Act (Public Law 90-396).

NOTE: At present the principal publication outlet for these data is the Journal of Physical and Chemical

Reference Data (JPCRD) published quarterly for NBS

by the American Chemical Society (ACS) and the American Institute of Physics (AIP). Subscriptions, reprints,

and supplements available from ACS, 1155 Sixteenth

St. N.W., Wash. D. C. 20056. Building Science Series—Disseminates technical infor- mation developed at the Bureau on building materials,

components, systems, and whole structures. The series presents research results, test methods, and performance criteria related to the structural and environmental

functions and the durability and safety characteristics

of building elements and systems.

Technical Notes—Studies or reports which are complete

in themselves but restrictive in their treatment of a

subject. Analogous to monographs but not so comprehensive in scope or definitive in treatment of the subject area. Often serve as a vehicle for final reports of work performed at NBS under the sponsorship of other government agencies.

Voluntary Product Standards—Developed under proce- dures published by the Department of Commerce in Part

10, Title 15, of the Code of Federal Regulations. The

purpose of the standards is to establish nationally rec- ognized requirements for products, and to provide all concerned interests with a basis for common understanding of the characteristics of the products. NBS

administers this program as a supplement to the activities of the private sector standardizing organizations.

Consumer Information Series—Practical information,

based on NBS research and experience, covering areas

of interest to the consumer. Easily understandable language and illustrations provide useful background knowledge for shopping in today's technological marketplace.

Order above NBS publications from: Superintendent

of Documents, Government Printing Office, Washington,

B.C. 201,02. Order following NBS publications—NBSIR's and FIPS

from the National Technical Information Services,

Springfield, Va. 22161. Federal Information Processing Standards Publications

(FIPS PUBS) —Publications in this series collectively constitute the Federal Information Processing Standards Register. Register serves as the official source of information in the Federal Government regarding stand- ards issued by NBS pursuant to the Federal Property

and Administrative Services Act of 1949 as amended,

Public Law 89-306 (79 Stat. 1127), and as implemented

by Executive Order 11717 (38 FR 12315, dated May 11, 1973) and Part 6 of Title 15 CFR (Code of Federal

Regulations).

NBS Interagency Reports (NBSIR)—A special series of interim or final reports on work performed by NBS for

outside sponsors (both government and non-government). In general, initial distribution is handled by the sponsor; public distribution is by the National Technical Information Services (Springfield, Va. 22161) in paper copy or microfiche form.

BIBLIOGRAPHIC SUBSCRIPTION SERVICES

The following current-awareness and literature-survey

bibliographies are issued periodically by the Bureau:

Cryogenic Data Center Current Awareness Service. A

literature survey issued biweekly. Annual subscription: Domestic, $25.00; Foreign, 830.00'. Liquified Natural Gas. A literature survey issued quarterly. Annual subscription: $20.00.

Superconducting Devices and Materials. A literature survey issued quarterly. Annual subscription: $30.00'.

Send subscription orders and remittances for the pre- ceding bibliographic services to National Bureau of Standards, Cryogenic Data Center (275.02) Boulder,

Colorado 80302.
,S. DEPARTMENT OF COMMERCE

•tional Bursau of Standards

9Shington. O.C. 20S34

FICIAL BUSINESS

jnalty for Private Use. S300

POSTAGE AND FEES PAIQ

U.S. DEPARTMENT QF COMMERCE

SPECIAL FOURTH-CLASS RATE

BOOK