Annals of Library Science and Documentation 1992, 39(4), 123-33

SOFlWARE DOCUMENTATION AND STANDARDS

Presently, software costs dominate the hardwarecosts in computer systems. Desire to produce highquality reliable software at low costs has led to theevolution and adoption of engineering principlesin the design and development of software. Thispaper deals with software documentation andstandards which occupy an important place insoftware engineering process. The need of asoftware librarian as a part of software engineer-ing team is discussed. International standards insoftware engineering deal with only guidelines.Evolving a standardisation process for an organ-isation using these guidelines is dealt with. Finallysome quality indicators for software documenta-tion are presented.

INTRODUCTIONThe last decade of computing recognised soft-ware as a new driving force and, in fact, softwaresurpassed hardware as the key element to thesuccess of many computing systems. But the dualproblem of high cost and low quality of software re-mains the main concern of the software engineer-ing community even today. Quality is sacrificedbecause of cost constraints, or costs are driven upin order to achieve higher levels of quality. De-ficiencies ignored during the development stageresult in huge costs during the maintenancephase of software systems. It is claimed by Boehm[1]that more than one-half of the total life-cycle costsare incurred during the maintenance phase.

During the past decade software developmenthas evolved into an engineering discipline. Soft-ware engineering techniques deal with softwareas an engineered product that requires planning,analysis, implementation, testing and maintenance.Although solutions to current problems in the do-main of software have advanced with the acknow-ledgement of life-cycle perspective of the devel-opment process, management's lack of commit-ment to educate existing talent in the use of evol-ving methodologies, techniques and tool continu-

Vol 39 No 4 Dee 1992

JMJOSET VlSWANATHANINSDOCNew Delhi

es to contribute to high-cost, low-quality software.

Citing the excessive software maintenance costs,the software engineering community has beenable to explain the need for a disciplined develop-ment process, controlled through meticulous at-tention to configuration management and gov-erned by a set of fundamental principles. In prac-tice, these principles are associated with the ob-jectives for a given software development activityand are measurable through associated attributesof the product.

Among these principles is the software documen-tation: i.e. the recording of the requirements, de-sign, specifications and implementation decisionsas they occur with the commitment to convey pur-pose, content and clari~.

SOFnNARE DOCUMENTATIONSoftware engineering techniques facilitate anengineering approach to software development.The classical life cycle approach goes throughdifferent phases such as requirements specifica-tions, design, coding, testing and maintenanceduring system development. The documentationof all these activities is necessary. A document isdefined as a written record of the completion ofa phase of work. Software documentation is a ma-jor component of software engineering activity asdepicted in Fig. 1. Software documentation com-prises the manuals and other descriptive informa-tion that portray the use, operation and othermajor components of the software.

The purposes of software documentation may becategorised into:

Inter-task/phase communicationQuality control and project controlHistorical referenceInstructional reference

123

VISWANAlHAN AND JOSE

MalntainancaRa qu I raman t. ....•Spaclflcatlon

.:I~Softwara Documantation

-> <.Spaei f ieat ion TastingDasign

V<,Coding

Figura 1

Designer!User !

Software Analyst ~ ---. Customer~ •..~~ .~

, IF, Ir

Builder!

Programmer .. System~

Figure 2

Plan Draft Edit

Review

Figure 3

124 Ann Lib Sci Doc

SOFfWARE DOCUMENTATION AND STANDARDS

Documentation serves as acommunication bridgebetween the user, the designer and the builder ofthe system as shown in Fig.2. It has long been rec-ognised that poor or inadequate communicationamong personnel is a major problem area in soft-ware development process. The system analystcommunicates with many user personnel duringthe investigation and analyses of the problemarea. The system analyst in turn communicatesthe program requirements to the programmer,who must specify how the computers must runthe program and so on. Without adequate docu-mentation, the initial idea from the user becomesdistorted resulting in the final product bearinglittle relation to the original intention. Documen-tation is important for quality assurance. As theproduct proceeds from concept to generaldesign and ultimately into operational form, theonly viable way to assess the product is throughits documentation. Documentation functions as asource for historical reference and the provisionsof a permanent record of work performed andused is an important reference for future modifi-cations. Documentation is also used as a instruc-tional device like user instructions or operatorinstructions.

A simple model of documentation process is shownin Fig.!3.

The first step in the documentation process isplanning the document. It consists of three mainsteps:

Define the audience, purpose, andsubjectOrganise the materialDesign the format

The second step in the documentation processis to create a draft, or working version of the docu-ment that has been planned. Once the draft is fin-ished, the next step is to edit it. The purpose ofediting is to refine the draft into a usable systemsdocument. When a useful version of the documenthas been drafted and edited, it has to be re-viewed. All documents need to be tested againsttheir document plan to make sure that they meetthe criteria defined there. Once the document hasbeen reviewed and perfected, it can be producedin a form that is suitable for distribution to the in-tended audience. Since information systems aremore susceptible to change, revision and updat-ing of system documents are important steps ofthe documentation process. The most importantfactors in good document design are:

Orderly development of ideas

Vol 39 No 4 Dee 1992

Technical accuracy and completen-essLogical arrangement of information

Software documentation can be defined as acollection of technical data or information, includ-ing computer listings and printouts, in humanreadable form. This collection describes or speci-fies the design details, explain the capabilities,or provide operating instructions for using thesoftware to obtain desired results from a softwaresystem.

There are standard procedures available for thedocumentation of activities done during differentphases of software development process. Thechanges made to the system during a particularphase of development should be reflected in allthe related documentation components. This isknown as concurrent documentation. The prin-ciples of concurrent documentation of softwareimplies a continual change to all documentationelements affected by changes at any stage of de-velopment, as depicted in Fig. 4. Concurrentdocumentation is particularly important within themaintenance phase because examination of exist-ing documents may be the only means availableto the maintenance personnel to understand theinternal details of the software and the original in-tentions of the developers. As with other softwareengineering principles, concurrent documenta-tion is crucial to the software development proc-ess, and later, to the maintenance activity.Hence, the extent to which concurrent documen-tation principle is observed must be measurableand controlled. This leads to the problem of de-termining how one might evaluate the quality ofdocumentation produced during the software de-velopment and maintenance phases.

Software documentation can be classified intosystem documentation and user documentationas depicted in Fig. 5.

. System documentation conveys the requirements,design philosophy, design details, capabilities,limitations and other characteristics of a system.User documentation conveys to the end user in-structions for using the system to obtain the de-sired results, tor example, a user's manual. Sys-tem documentation,in addition,can be categorisedinto tour applicational areas as shown in Fig.5.

Software Requirement Analysis documentation

Requirement analysis is the process of allocat-ing software function, in the overall system devel-opment process. It enables the system analyst to

125

VISWANATHAN AND JOSE

Req..SpecDes. Spec.

Doc. Coding

Change

Figure 4

Software Documentation

.II J I System Doc.

User Doc.

Requirements

I Design II

I ProgramI

I TestingI, "I

Figure 5

Plan Req. Spec.

Test Spec.

Figure 6

126 Ann Lib Sci Doc

SOFIWARE DOCUMENTATION AND STANDARDS

specify software function and performance, indi-cates software's interface with other system ele-ments, and establishes design constraints thatsoftware must meet.

Software Requirements Specification is producedat the culmination of the analysis task.The functionand performance allocated to software as part ofsystem engineering are refined by establishing acomplete information description, a detailed func-tional description, an indication of performance re-quirements and design constraints, appropriatevalidation criteria, and other data pertinent to therequirements. In general a requirement documentshould include:

Introduction It states the goalsand Objectives of the software, describing it in thecontext of the computer based system.

Information Description - It provides de-tailed description of the problem the softwaremust solve.

Functional Descriptions - A descrition ofeach function required to solve the problem is pre-sented.

Validation Criteria It specifies whatclasses of tests must be coducted to validatefunction, performance and constraints.

Bibliography and Appendix - Bibliography con-tains references to all documents that relate tosoftware. The appendix contains information thatsupplements the specifications.

ANSI/IEEE Std 830-1984 specifies in detail whatare the components of a good requirements docu-ment. The guide describes alternate approachesto good practice in the specification of software re-quirements. To enable the reader to make knowl-edgeable choices, extensive tutorial material isprovided. This covers the attributes of a good soft-ware requirements speCification itself, as well asspecification methodologies and associated for-mats.

Design Documentation

Software design is a process through which re-quirements are translated into a reprosentation ofsoftware. Softwarr design is conducted in twosteps. Preliminary aesign is concerned with thetransformation of requirements into data andsoftware architecture. Detailed design focuseson refinements to the architectural representa-tion that lead to detailed data structure and algo-

Vol 39 No 4 Dee 1992

rithmic representation for software.

A design document consists of scope of software,reference documents, design description, mod-ules, file structure, global data, requirements cross-references, test procedures, etc. The documentsshould specify the necessary information con-tent. A software design document is a represen-tation of a software system that is used as a me-dium for communicating software design informa-tion. ANSI/IEEE Std 1016-1987 specifies an or-ganisation for a software design description.

Program Documentation

Program documentation comprises the records ofthe detailed logic and coding of the constituentprograms of a system. It is prepared by the pro-grammer and aids:

Program development and acceptan-ceTrouble shootinqProgram maintenanceMachine conversionProgrammer change over

For the purpose of program documentation, thefollowing guidelines are useful:

heading comments for the main pro-gram and each subroutine to provide the readerwith an overall information about the programstructure and logic, and with a concise descrip-tion of the functions of each component.

current comments strategically placedwithin the program to identify logical divisions orblocks, to clarify programs statements, and topoint out deviations from the standard program-ming language, if any.

Program documentation should contain detailssuch as: who developed the code and when, whomade the changes and why, what changes aremade and when in a chronological order.

Test Plan Documentation

The preparation of a program test plan is a funda-mental technique of program validation methodol-ogy. A test plan is essentially a schedule of se-quence operations to test a program. The testplan incorporated in the program manual shouldnominally comprise:

•

A summary of methodList of test cases, sequence of appli-

127

VISWANAlliAN AND JOSE

MaintenanceReQueete

Change ControlAuthority

••• <Om ••• ervt •• ,!Meintenance

Controller "-a

Contlg. Manager(Librarian)

Maintenance Slall

Figure 7

Adequate Documentation

Accuracy

Figure 8

128Ann Lib Sci Doc

SOFTWARE DOCUMENTATION AND STANDARDS

cations and expected resultsListing of a test data

ANSI/IEEE Std 829-1983 specifies the contentsof a test documentation. The standard addressesthe documentation of both initial developmenttesting and testing of subsequent releases. Thedocuments outlined in this standard cover testplanning, test specifications, and test reporting.The test plan prescribes the scope, approach,resources and schedule of testing activities. Itidentifies the items to be tested, the features to betested, the testing tasks to be performed, thepersonnel responsible for each task, and the risksassociated with the plan. The standard shows therelationships of these documents to one anotheras they are developed, and to the test processthey document.

SOFTWARE DOCUMENTATION AIDS

The most common type of software documen-tation aid is the automatic flowchart generator orflowcharter. These talljnto two main groups. Thefirst group operates on ordinary source programmestogether with a few special parameters to producedetailed logic flowcharts. The second group acceptsspecial parameters plus a program descriptionand from these, an outline flowchart is produced.The tirst group of flow charts are called post cod-ing flowcharts, and are valuable aids for programmaintenance. The second group of flow chart canbe called as precoding flowcharts. A flowchartingpackage can also produce reference listings.

Automatic Software Documenter is one such pack-age developed by the firm COSMIC, Georgiaandworks on HP-9000 systems. This software pro-vides automated drafts of documentation directlyfrom C source code in the Unix environment. Thisis specifically designed to simplify and stream-line program ciocumentation. BOS/HLP is anotherpackage which helps to create on-line documen-tation interactively. Documentation Aid from Allensystems group generates and helps to maintainjob documentation, provides on-line retrieval, andcross-referencing. All flowcharters available tran-scribe the sequential program flow. Some, how-ever, have the option to present the logic in adifferent form. For example, AUTOFLOW fromApplied Data Research Inc. automatically analy-ses the program, determines which logical units ofcode are related, and, whenever possible, placesthese blocks of logic together on the chart, regard-less of their input sequence, DOCUMATIC fromData usage Corporation, USA does not producedetailed flow chart as such but an outline systempictorials(inputs, outputs, and process box) to-

Vol 39 No" Dee 1992

get her with a narrative description of processing.

USER DOCUMENTATION

User documentation is the hardcopy or on-linedocumentation provided with an application prog-ram. It tells the user how to get the program upand running, trains the user in its operation, andprovides reference information once the userbecomes experienced.

User documentation is extremely important. It willmake the difference between whether a programcan be used effectively or not. User documenta-tion is increasingly becoming a selling point forsoftware products.

User Documentation development process con-sists of the following stepsla].

a) Form the documentation developmentteam

b) Make user documentation matchc) Prepare documentation plansd) Develop documentation standardse) Develop management planf) Create documentationg) Conduct technical reviewh) Conduct user evaluationi) Create final draft,

The larger and more complex the program, it ismore likely that it will need several separate docu-mentation components to fulfill various needs ofits audience, The documentation developer mustdecide what components are needed in the func-tion to be fulfilled by each.

User documentation comes in two forms: internaland external. Internal documentation consists ofhelp screens, directions and other explanatoryinformation that the operator can access within theprogram. External documentation is outside theprogram itself. Its most common form is user'sguide,

All user documentation has the same purpose: toexplain the features of the program and help theoperator gain proficiency in using it. The mostcommon forms of external documentation proba-bly are the program user's guide, quick refer-ence card, quick reference guide, and job per-formance aid, The most common forms of internaldocumentation probably are the help screen,tutorial and gu!_dedtour.

A user documentation system is a set of interde-pendent documentation components designed to

129

VISWANATHAN AND JOSE

support the user in learning and using theprogram.The various components have differentpurposes and support this goal in different ways,but all, in one way or another support the ultimategoal.

The major components are

On-line help (provide fast access tokeS'commands and procedures)Tutorials (trains new users)Reference manual (provides detailedreference information)Job performance aid (summarizes keyprocedures)Guided tour (provides program overview)System set up information (tells howto configure program)Quick reference card (provides keyreference information)

ANSI/IEEE Std 1063-1987 is the standard forSoftware User Documentation. This standard pro-vides minimum requirements on the structure andinformation content of user documentation. It dealsprimarily with the technical substance rather thanthe style. Users of the standard may develop theirown style manual for use within their organisationsto implement the requirements of this standard.

SOFTWARE UBRARIAN

Concurrent documentation facilitates consistencyin documents. During maintenance phase andother phases of development process, the changesattributed to one document should reflect in otherdocuments also. Otherwise, inconsistency will resultand defeats the purpose of documentation.

To ensure the quality and reliability of the soft-ware, one will have to be authorised to monitorand control the changes attributed atthe main-tainance phase of the software development. Theanswers to the questions, such as :

How does an organisation identifyand manage the many existing versions of a pro-gram (and its documentation) in a manner that willenable Change to be accomodated efficiently?

How does an organisation controlchanges before and after software is released toa customer?

How does one ensure that changeshave been made properly in all related compo-nents?

130

lead to the concept of a software librarian or con-figuration manager. The outputs of a softwareengineering process are collectively called software configuration, as depicted in Fig.6 ..

Software configuration management is a set ofactivities developed to manage changes through-out the software life cycle. It is a software qualityassurance activity. ANSI/IEEE Std 828-1990 givesthe standard for software configuration manage-ment planning. The purpose of this guide- is toprovide guidance in planning software configura-tion management (SCM) practices that are com-patible with ANSI/IEEE Std 828-1983. The guidefocuses on the process of SCM planning andprovides a broad perspective for understandingsoftware configuration management [4].

In a software development process a softwarelibrarian is responsible for keeping all the docu-ments related to a software development proc-ess. He is a part of the software maintainance/development team (Fig.7) Whenever changes aremade to one document, software librarian isresponsible for making the related changes to alldocuments. He constantly interacts with mainte-nance staff, development teams, system supervi-sor, review team, testing team etc. The librarianacts as a controller, coordinator and potentially anevaluator of the software configuration.

The responsibilities of a software librarian are tomaintain custody of programs, files, documenta-tion, magnetic media; help collect and formatsoftware productivity data, catalogues and in-dexes revisable and reusable software module,and assist the team in research, evaluation, anddocument preparation.

He is also responsible for concurrent documenta-tion, i.e. issue of these resources based on au-thorized schedule of use or special authorisation.He schedules changes to production applicationsafter completion of testing and maintains recordsof the changes.

Even though a large number of software packagesare available for document preparation and main-tainance there is no software available to ensurethe changes made in one document automati-cally leads to changes in other related documents.

INTERNATIONAL STANDARDS

For ensuring quality of software products, stan-dards organisations such as IEEE and ISO havecome up with standards for different softwareengineering activities. A list of the latest standards

Ann Lib Sci Doc

from IEEE[2] are given in Appendix-I

SOFTWARE DOCUMENTATION AND STANDARDS

The Standards from International StandardsOrganisation(lSO)give another set of guidelinesfor softWare documentation. The standard ISO9000 is for quality systems and gives a model forquality assurance in design/development, produc-tion, installation and servicing. It has three parts:

Part 1. ISO 9001 Specification for de-sign/development.

Part 2. ISO 9002 Specification for pro-duction and installation.

Part 3. ISO 9003 Specification for finalinspection and test.

ISO 9000-3: 1991 (E) sets out guidelines, to facili-tate the application of ISO 9001 to organisationsdeveloping, supplying and maintaining software.

BS ISO/IEC TR 9294:1990 -Information Technol-ogy - Guidelines for management of SoftwareDocumentation gives the specific guidance on theManagement of software documentation to thosemanagers responsible for the production of soft-ware or software based products.

DEVELOPMENT OF DOCUMENTATION STAN-DARDS

There is no universal documentation system whichis valid for all environments. Development of docu-mentation standards should, to a large extent, bea process of adaptation rather than origination.The standards available from IEEE and ISO act asguidelines. For example, ANSI/IEEE Std 1002-1987 explains the Taxonomy used in softwareengineering standards, their functional and exter-nal relationships and the role of various functionsparticipating in the software life cycle. This Taxon-omy may be used as a method for planning thedevelopment or evaluation of documentation stan-dards for an organisation. There are three phasesin evolving documentation standards[5] :

preparatory phasedevelopment phasepost implementation phase-audit, ma-intenance and support.

Three major preparatory tasks in the preparatoryphase are:-

workout project organisation and al-locate resources.define scope of standards program.

Vol 39 No 4 Dee 1992

define the architecture or organisati-on of manuals.

Development phase as such contains the actualstandard development process. It is necessary to:

Provide the groundwork for develop-ment of each standard.Determine the formal and informalpractices in effect.Gather data for comparison of thevarious approaches or possible so-lutions.Establish priority of needs and proba-bility for successful implementation.

It also involves the draft preparation, distributionof draft etc. In post-implementation phase, proce-dures must be formulated to review and maintainthe standards.

The output of the standard developments pro-gram should be:

A manual for documentation standa-rdsA maintenance and support programA training and implementation scheme

DOCUMENT QUAliTY INDICATORS

Arthur & Stevens [6] described a method forevaluating the adequacy of predefined, static setsof documentation relative to the system that itpurportedly describe. The primary,high-Ievel quali-ties of good documentation are: accuracy, com-pleteness, usability and expandability. Qualitiesare the abstract characteristics of adequate docu-mentation, yet, essential to its definition. As shownin Fig. 8, qualities are the nodes directly under andmost closely tied to the even more abstract notionof adequate documentation.

Although intangible, the identified qualities mostclosely convey the meaning of adequate docu-mentation. For the purpose of clarity, a brief de-scription of all four qualities are given below:

Accuracy The common definition for 'ac-curacy' is the freedom from mistake or error; asynonym is 'correctness'. Within the context ofcomputer documentation, accuracy can be de-fined as the consistency among the code and alldocumentation of the code for all requirements.That is, accurate documentation should reflectthe realized state of the system that it represents.

Completeness: The standard definition for

131

VISW ANA THAN AND JOSE

'completeness' is the possession of all neces-sary parts, elements, or steps. For the purposesof computer documentation, a set of documenta-tion is complete if all of the required information ispresent.

Usability The dictionary definition forusability' is the capability, convenience, or suita-bility of being employed. Relative to assessingdocumentation quality, usability is more appropri-ately defined as the suitability of the documenta-tion relative to the ease with which one can extractneeded information.

Expandability: A general definition for expanda-bility is the ability to increase an object's extentnumber, volume, or scope. A synonym is 'exten-sibility'. The rationale for including expandabilityas a desirable quality is to reflect concepts under-lying document maintainability, and in particlarthe ease with which thedocumentation can beadded to and modified. In concert with the notionof document maintainability, a more precise defi-nition for expandability is: the capability of thedocumentation to be modified in reaction to changesin the system.This quality is assessed throughmeasures reflecting ease of modification.

SUMMARY

latest standards in software engineering, withparticular emphasis on documentation is discussedhere. The needs. of documentation and its variouscomponents are discussed in detail, from the viewpoint of software engineering. svstem documen-tation, an integral component of software docu-mentation, conveys the requirements, design phi-losophy, design details, capabilities, limitationsand other characteristics of a system while userdocumentation, another component of softwaredocumentation conveys to the end-user instruc-tions for using the system to obtain desired re-sults. The principle of concurrent documentationemphasises that the changes made to the sys-tem during a particular phase of developmentshould be reflected in all the related documenta-

132

-tion components. This brings out the need for asoftware librarian, which has been discussed indetail in this article. A universal documentationsystem which is suitable for all types of organisa-tion is not available, but each organisation candevelop its own standard documentation proce-dures from the guidelines given by the standardsavailable.

For evaluating the adequacy of a document, a setof quality indicators such as accuracy, complete-ness, usability and expandability are to be givendue importance.

ACKNOWLEDGEMENTS

Shri J M Jose is thankful to the CSIR for support-ing this work.

REFERENCES

1. Boehm B: Software engineering, IEEETran on Computers. 1976, C-25, 1226-1241.(1976)

2. IEEE: Standards of software engineer-ing. IEEE Inc. August 1990

3. Simpson H and Casey S M: Developing effective user documentation. McGraw Hill 1988.

4. Pressman RS: Software Engineering- A practitioners approach, Mc.GrawHill,1987

5. london K R: Documentation Standa-rds. New York, Petrocelli books, 1974

6. Arthur J D and Stevens KT: Docum-ent quality indicators - A Frame workfor assessing documentation adequ-quacy, Software maintainace: Res-search & Practice. 1992, 4, .129-142(1992) .

Ann Lib Sci Doc

SOFTWARE DOCUMENTATION AND STANDARDS

APPENDIX-I

List of latest standards from IEEE

ANSI/IEEE Std 729-1983 Glossary of Software Engineering Terminology

ANSI/IEEE Std 730-1989 Software Quality Assurance Plans

ANSI/IEEE Std 828-1990 Software Configuration Management Plans

ANSI/IEEE Std 829-1983 SoftwareTest Documentation

ANSI/IEEE Std 830-1984 Guide for Software Requirments Specifications

ANSI/IEEE Std 982.1-1988 Standard Dictionary of Measures to Produce Reliable Software

ANSI/IEEE Std 982.2-1988 Guide for the Use of IEEE Standard Dictionary of Measures toProduce Reliable Software (IEEE Std 982.1-1988)

ANSI/IEEE Std 983-1986 Software Quality Assurance Planning

ANSI/IEEE Std 990-1987 Ada As a Program Design Language

ANSI/IEEE Std 1002-1987 Taxonamy of Software Engineering Standards

ANSI/IEEE Std 1008-1987 Software Unit Testing

ANSI/IEEE Std 1012-1986 Software Verification and Validation Plans

ANSI/IEEE Std 1016-1987 Software Design Descriptions

ANSI/IEEE Std 1028-1988 Standards for Software Reviews and Audits

ANSI/IEEE Std 1042-1-987

ANSI/IEEE Std 1058.1-1987

Guide to Software Configuration Management

Standard for Software Project Management Plans

ANSI/IEEE Std 1063-1987 Standard for Software User Documentation

Vol 39 No 4 Dee 1992 133