.

A St andar d for
Standards

unique requirements of consumer-ori-

ented software. As a general guideline for
clear, well-organized documentation,
however, the ANSI/ANS 10.3-1995 stan-

Soft w ar e
dard can serve as a fine place for devel-
opers to begin a documentation
methodology.
The standard itself is not only well

Document at ion
written and fairly comprehensive, but it
allows for individual developer differ-
ences and unique software documenta-
tion problems. In short, the AN SI/AN S
10.3-1995 standard provides a flexible,
Vir Phoha, Northeastern State University robust framework for documentation
needs.

CONTENT RATHER THAN FORM

The ANSI/ANS 10.3-1995 standard—
which makes recommendations for the
content rather than the form of software
tandardizing software docu- documentation—suggests separating

S
mentation could help reduce the documentation content into four cate-
time and effort spent in devel- gories: the abstract, the application infor-
oping new software, increase mation, the problem (or function)
the ease of porting software to definition, and the programming infor-
different platforms, and help users mation. The standard also makes rec-
understand software more easily. But ommendations as to which items to
there is no universally recognized stan- include in the software package itself,
dard for software documentation, in such as floppy disks and manuals, and
part because documentation style and even how best to label those disks and
content differ among programmers and manuals. But the most useful elements of
sometimes differ for the same program- the standard are the four content cate-
mer under different circumstances. In The ANSI/ANS 10.3-1995 gories themselves.
addition, the choice of programming standard provides a
language and the nature of a program flexible, robust framew ork Abstract
may dictate a particular style of docu- for documentation needs. The abstract summarizes the soft-
mentation that might not easily apply to ware’s major capabilities and purposes.
another environment. The abstract’s goal is to provide the user
While there is no universally recog- with enough information to enable an
nized standard for software documenta- the standard itself, is “ to encourage bet- easy decision about whether the software
tion, there is a standard for documenting ter communication between developer is suitable for the user’s needs. According
engineering and scientific software. and user, and to facilitate effective selec- to the standard, this information should
Developed by the American N ational tion, usage, transfer, conversion, and
Standards Institute and the American modification of computer software.” The
N uclear Society in 1995, it is called standard is not a rigid set of specifica-
AN SI/AN S 10.3-1995 Standard for tions, but a guide that can apply to most Where to Obtain the Standard
Documentation of Computer Software. software projects intended for internal The standard costs $55 and can be
O ne of the standard’s goals, as stated in or external use. ordered through the AN SI Web site
While the standard cannot cover all (http://www.ansi.org) or by contact-
documentation problems, it is a good ing AN SI at the following address:
Editor: Charles Severance, Michigan State starting point, even for the most complex American N ational Standards
University, Department of Computer software. Similarly, while the standard Institute
Science, 1338 Engineering Bldg. , East provides recommendations for docu- 11 W. 42nd Street
Lansing, MI 48824; voice (517) 353-2268; menting scientific and engineering soft- N ew York, N Y 10036
fax (517) 355-7516; crs@egr. msu. edu; ware, it doesn’t offer guidance for online Phone: (212) 642-4900
http://www. egr. msu. edu/~crs monitoring, control, or safety systems, Fax: (212) 398-0023
and doesn’t specifically address the

October 1997 97
.

Standards

include specific functions of the software, limits of the software’s capabilities and gramming information section about the
the required computer environment, and exactly how the software calculates and environments on which the software has
all the materials available to the user in processes data. been tested, the specific memory require-
the software package, including manu- The functional definition also ments needed by the target platform, the
als. describes the software’s data libraries and special hardware functions the software
the way the software processes were val- uses, the unique networking require-
Application information idated by the developer. The goal of this ments, the language processors, the sub-
The application information section section, according to the standard, is “ to routine libraries, and much more.
summarizes the problems the software is provide sufficient detail to permit users
designed to solve, and specifies how to to judge the suitability of any model for RELATED M ATERIALS
use the software, especially for prepar- application to a particular situation.” The standard also makes recommen-
ing input data and interpreting computed dations for what should be included in
results. This section should be concise the software package itself. The software
enough to enable effective use of the soft- The standard can even package, according to the standard, is
ware and to serve as a reference source be helpful for budding the “ aggregate of all elements required
for user questions. It also includes a brief softw are developers for implementation or use of the soft-
discussion of the comparative strengths w orking in classrooms ware,” including documentation, sam-
and weaknesses of the software in rela- ple output, and transmittal material. The
or garages.
tion to other competing or related soft- standard makes useful recommendations
ware packages. for how disks should be labeled, how the
The application information describes contents of the software should be iden-
Programming information tified in external documents, and how
• the function of each major program The programming information section developers should include sample data
option; is for people who implement, maintain, sets.
• the way the software handles files; modify, and port software for external There are also recommendations for
• the effect of data storage require- or local needs. While this section would an installation environment report,
ments on the software; likely not be included in consumer-ori- which—like the programming informa-
• the range of values and variables ented software, it is a useful part of the tion section—would document all the
that can be used in the software; documentation process, especially be- computer environments on which the
• the control commands required to cause it can help track changes to soft- software has been tested.
execute the program; and ware as it moves to different platforms
• the nature of the output, including or computing environments.
the way the output relates to the The programming information offers hile it might seem as if the
input.

The application information also pro-

• the language in which the program
was written and details about any
W AN SI/AN S 10.3-1995 standard
is unnecessarily comprehensive
in its recommendations, it is unques-
vides information on how to recover development tools used, tionably useful. O ffering a complete
from a crashed application, how to • details that would help port the soft- checklist of software and hardware
restart the application, and how to inter- ware to different platforms, details, the AN SI/AN S 10.3-1995 stan-
act with the software’s various data • specific descriptions of the types of dard will also be useful to developers
screens. This section provides basic infor- data files and internal devices the who have their own methods of software
mation on how much of the computer’s software uses, documentation. The standard can even
memory and processor power the appli- • implementation requirements, and be helpful for budding software devel-
cation uses. • the control commands to install the opers working in classrooms or garages.
software. Programmers’ workloads will initially
Functional definition increase when they adhere to the stan-
The functional definition addresses the The programming information section dard—because successful documenta-
algorithms or mathematical models used includes complete diagrams that help tion takes time—but the payoff in terms
in the program. This section won’t be illustrate a program’s structure and logic, of reuse and portability is clear. ❖
of interest to those using the software and includes flowcharts where appro-
unless users want to understand and val- priate. The programming information
idate the nature of the mathematical section also identifies ways to describe
models the software is built upon. This the software’s network interface and Vir Phoha is assistant professor of com -
section contains a very detailed descrip- data-transfer protocols. puter science at N ortheastern State Uni-
tion of the problems that can be solved The standard recommends including versity, Tahlequah, O k lahom a; contact
with the software, including the outside very detailed information in the pro- him at phoha@cherok ee.nsuok .edu.

98 Computer October 1997 98