NATL INST OF STAND & TECH AlllDt. ^7fl3fiE Computer Science National Bureau of Standards and Technology NBS Special Publication 500-94 NBS FIPS NBS Software Documentation PUBLICATIONS NATIONAL BUREAU OF STANDARDS The National Bureau of Standards' was established by an act ot Congress on 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 promote public safety. The Bureau's technical work is per- formed by the National Measurement Laboratory, the National Engineering Laboratory, and the Institute for Computer Sciences and Technology. THE NATIONAL MEASUREMENT LABORATORY provides the national system of physical and chemical and materials measurement; coordinates the system with measurement systems of other nations and furnishes essential services leading to accurate and uniform physical and chemical measurement throughout the Nation's scientific community, industry, and commerce; conducts materials research leading to improved methods of measurement, standards, and data on the properties of materials needed by industry, commerce, educational institutions, and Government; provides advisory and research services to other Government agencies; develops, produces, and distributes Standard Reference Materials; and provides calibration services. The Laboratory consists of the following centers: Absolute Physical Quantities^ — Radiation Research — Chemical Physics — Analytical Chemistry — Materials Science THE NATIONAL ENGINEERING LABORATORY provides technology and technical ser- vices to the public and private sectors to address national needs and to solve national problems; conducts research in engineering and applied science in support of these efforts; builds and maintains competence in the necessary disciplines required to carry out this research and technical service; develops engineering data and measurement capabilities; provides engineering measurement traceability services; develops test methods and proposes engineering standards and code changes; develops and proposes new engineering practices; and develops and improves mechanisms to transfer results of its research to the ultimate user. The Laboratory consists of the following centers: Applied Mathematics — Electronics and Electrical Engineering^ — Manufacturing Engineering — Building Technology — Fire Research — Chemical Engineering^ THE INSTITUTE FOR COMPUTER SCIENCES AND TECHNOLOGY conducts research and provides scientific and technical services to aid Federal agencies in the selection, acquisition, application, and use of computer technology to improve effectiveness and economy in Government operations in accordance with Public Law 89-306 (40 U.S.C. 759), relevant Executive Orders, and other directives; carries out this mission by managing the Federal Information Processing Standards Program, developing Federal ADP standards guidelines, and managing Federal participation in ADP voluntary standardization activities; provides scientific and technological advisory services and assistance to Federal agencies; and provides the technical foundation for computer-related policies of the Federal Government. The Institute consists of the following centers: Programming Science and Technology — Computer Systems Engineering. 'Headquarters and Laboratories at Gaithersburg, MD, unless otherwise noted; mailing address Washington, DC 20234. 'Some divisions within the center are located at Boulder, CO 80303. or STMTDMUIB UBwuty DEI 1 198? Computer Science r ^ and Technology NBS Special Publication 500-94 NBS FIPS Software Documentation Proceedings of a Workshop Held March 3, 1982 at NBS, Gaithersburg, MD. A.J. Neumann, Editor Institute for Computer Sciences and Technology National Bureau of Standards Washington, DC 20234 U.S. DEPARTMENT OF COMMERCE Malcolm Baldrige, Secretary National Bureau of Standards Ernest Ambler, Director Issued October 1982 Reports on Computer Science and Technology The National Bureau of Standards has a special responsibility within the Federal Government for computer science and technology activities. The programs of the NBS Institute for Computer Sciences and Technology are designed to provide ADP standards, guidelines, and technical advisory services to improve the effectiveness of computer utilization in the Federal sector, and to perform appropriate research and development efforts as foundation for such activities and programs. This publication series will report these NBS efforts to the Federal computer community as well as to interested specialists in the academic and private sectors. Those wishing to receive notices of publications in this series should complete and return the form at the end of this publication. Library of Congress Catalog Card Number: 82-600600 Natl. Bur. Stand. (U.S.) Spec. Pub. 500-94, 294 pages (Oct. 1982) CODEN: XNBSAV U.S. GOVERNMENT PRINTING OFFICE WASHINGTON: 1982 For sale by the Superintendent of Documents, U.S. Government Printing Office, Washington, D.C. 20402 Price $8.50 (Add 25 percent for other than U.S. mailing) Acknowledgement The support and assistance which have made this workshop possible are gratefully acknowledged. The steering committee and the program committee, whose names are listed separately, have worked for over a year diligently and intensely to shape the program and to organize the sessions. I wish to express my appreciation to all committee members, authors, discussants, recorders, session chairs and the organizations, both in the private sector and in Government, who supported the participants. Special thanks are due to Leo Beltracchi, who contributed materially to the planning, organization, and success of this workshop. A.J.N. Disclaimer The viewpoints expressed by participants in this workshop are those of the individuals and not those of organizations, agencies, or individual companies. Workshop Organization Workshop Chair: Albrecht J. Neumann, National Bureau of Standards Program Chair: Leo Beltracchi, U. S. Nuclear Regulatory Commission Publicity Chair: Virginia C, Walker, U. S„ Department of Energy Treasurer: Bonnie S. Eilertson, National Bureau of Standards Arrangements: Greta D. Pignone, National Bureau of Standards Exhibit: Thomas Q. Stevenson, U. S. Department of Agriculture Steering Committee: Leo Beltracchi, LI. S. Nuclear Regulatory Commission Charles H. Dickson, Jr., U. S. Department of Agriculture Trudy Grieb, Hadron, Inc. Thomas M. Kurihara, U. S. Department of Transportation Albrecht J. Neumann, (Chair), National Bureau of Standards Samuel T. Redwine, Jr„, The MITRE Corporation Charles S. Shimkus, U. S. General Accounting Office Thomas Q. Stevenson, U. S. Department of Agriculture Virginia C. Walker, U. S. Department of Energy C. Robert Mangum, U. S. Department of Defense Saul Zeveler, U. S. Air Force Program Committee: Leo Beltracchi, (Chair), U. S. Nuclear Regulatory Commission Charles H. Dickson, Jr„, U. S„ Department of Agriculture Charles L. Gerhardt, U. S„ Department of Agriculture Trudy Grieb, Hadron, Inc. Raymond C. Houghton, National Bureau of Standards Lenore S. Maruyama, Library of Congress Albrecht Jo Neumann, National Bureau of Standards Joseph Psotka, National Institute of Education Alfred R. Sorkowitz, U. S. Department of Housing and Urban Development Virginia C. Walker, U. S. Department of Energy NBS FIPS Software Documentation Workshop, March 3, 1982 INTRODUCTION -This workshop is the result of over a year's work by a group of people who feel that software documentation has an important place in software and overall systems development. The purpose of the workshop was to review current documentation standards and guidelines, to provide a forum for information exchange, and to propose and discuss future guidelines and standards for software documentation. In order to determine the scope of the workshop, to obtain some idea of what topics would be of interest, and who the audience might be, a "Call for Indications of Interest", was issued, with a deadline of May 15, 1980. The response was generous, and by October 1980, a preliminary program was finalized. The program was planned to be a regional affair, covering commuting distance from Washington, D.C., Maryland, and Virginia. In the following pages there are presented introductions by session moderators, papers presented, comments by discussants, recorders, and members of the audience. It is hoped that the record of this workshop will contribute to the identification and clarification of software documentation issues, will help in solving some of the issues, and will thus contribute to the development of better and more useful information systems. The final program, as it was presented, has been reproduced, and references to page numbers in the Proceedings provide an index to the presented material. V NBS FIPS Software Documentation Standards Workshop, Wednesday, March 3, 1982 PROGRAM 8:30 a,m. REGISTRATION 9:15 a.m. GENERAL SESSION - OPENING REMARKS Welcome: James H„ Burrows, Director, Institute for Computer Sciences and Technology, National Bureau of Standards Charge to Workshop: Albrecht J. Neumann, Institute for Computer Sciences and Technology, National Bureau of Standards 10:00 a„m„ BREAK 10:15 a.m. - 12:30 p.m. MORNING PARALLEL SESSIONS SESSION