You are on page 1of 16

A Proposal for Software Documentation

Because of major past disasters software development has been forced to establish
processes that can be defined, repeated, managed, and optimized. Technical
documentation is finally coming into its own as a mature process; and faces pressure to
follow suit by formalizing the processes for documentation systems development.
Software engineering is a relatively new field of expertise, with the more recent nonproprietary formalizations of the software development life cycle being the Institute of
Electrical and Electronics Engineers (IEEE) Standard 12207, and the Capability Maturity
Model-Integrated (CMM-I) of the Software Engineering Institute (SEI).
We propose formalizations of the software documentation processes based on the IEEE
12207 standard, the one mandated by the U.S. Department of Defense. It will be found
that this standard goes a long way towards, if not actually fulfilling CMM-I
recommendations. This proposal also may be re-worked as a universally applicable
standard for a documentation system development life cycle (DSDLC).

Central to this discussion is that increasingly complex software applications upon which
human life depends require the best documentation possible. For example, modeling and
simulation programs increasingly are being used to drive uninhabited autonomous
systems. Failure to track their behavior through validation and high quality
documentation can result in runaway scenarios beyond human control. Documents need
to be integrated into a system that conveys information not only about particular aspects
of software development, but the deployment and subsequent management of the
software. Preparation of documents, as in software development, is only a relatively
small part of the development life cycle. They must be tested, deployed, and managed.
To accomplish this, it is essential to have in place a sound documentation system
development life cycle.

The Microcosm of Document Development

Typical employment ads for technical writers call for a knowledge of specific tools, such
as desktop publishing software, good communications skills, and the ability to manage
Organizations want technical writers to produce good documents that minimally:

Translate the complex into a form that an end-user can understand

Exercise consistency in carrying out the goal of an action (present information the
same way every time)
Accurately reflect that which is being described

Technical writing as an evolving discipline

Page 1 of 16

Documents should be checked for:

Overall appearance
Technical accuracy
Language mechanics
Quality and relevance of illustrations

Documents generally contain a:

Cover page
Title page
Table of Contents
Approval information
ISO-compliant revision tracking
Proprietary statement (when necessary)
Index (when appropriate)

This type of checklist applies to paper documents as well as other media. When the
concept of documentation is expanded to include knowledge management or
information management, additional criteria and processes for content delivery are
added. This is to be discussed in greater detail below.

EXAMINING the Context of Individual Document Preparation

Documentation is crucial to the success of most projects; without it, many products
would be useless to the end-user. Often, larger documentation efforts require a division
of labor in preparing the documents, hence creating critical concern for how the
documents interrelate with each other and the project. In a large scale documentation
effort, separate but coordinated staffs do information gathering and initial writing,
illustrating, editing, testing, and proofreading, normally because each of these activities
involves specialized knowledge and skills.
Documentation managers are learning to look beyond the immediacy of the document to
include its environment. Information gathering, analysis, and dissemination have
evolved collectively into their own separate disciplines, similar to the way that software
engineering, in the last 15 years or so, replaced the haphazard development common in
the days of spaghetti code. No longer should anyone think that an informal approach to
technical writing is sufficient to complement software/product development. As with
software development, documentation efforts need to be formalized.

Technical writing as an evolving discipline

Page 2 of 16

Documentation that has not been integrated into a life cycle can present expensive
problems, not to mention potentially life-threatening situations. When instructions do not
match what is supposed to be done, or when diagrams do not match the equipment or
actual screens, clearly, the documentation has not been tested properly and has not passed
muster A documentation life cycle not only concerns a defined process of gathering and
writing about information, but the applicability of that writing is qualified by testing.
While, the Software Engineering Institute (SEI), Association for Computing Machinery
(ACM), and the Institute for Electrical and Electronics Engineers (IEEE) give peripheral
attention to documentation, documentation development can be more effective when
integrated with their overall software development standards. The documentation
development process model discussed here can be applied to software, manufacturing,
business, or engineering environments. (Note: The Project Management Institutes
Project Management Body of Knowledge (PMBOK) 2 addresses documentation; however
it does not address documentation life cycles.)

WHAT Currently Exists In search of a Documentation

Life Cycle
Four major organizations concerned with computer software and documentation methods
are the Society of Technical Communicators (STC), IEEE, ACM, and SEI.
The STC has templates for validating a document,which includes the essential categories
within a document. Yet, the STC recognizes the value of CMM-I. 5 Often, individual
installations have their own guidelines. However, in the case of the U.S. Department of
Defense (DoD), this changed in 1998, when all military units were required to follow the
Institute of Electrical and Electronics Engineers (IEEE) Standard 12207. Additionally
there has been a need to show that a documentation system method can accommodate
other documentation methodologies, such as the Rational Unified Process (RUP). While
the numerous helpful templates on the STC website6 may be useful, and while these
templates are useful, it would be more useful to track the IEEE 12207 standard, albeit
amplifying it with information from the validation template. What is proposed here
fulfils CMM-I guidelines.
The IEEE Professional Communication Society Newsletter (published by the official
IEEE documentation society) had an article about a DSDLC for individual documents,
but again, the life cycle for the ensemble of documents was not discussed.7 The model
was originally published by Pawan Nayar (from the East Indian STC website8) and uses
the Microsoft Solutions Framework Mode, surprisingly, not from the IEEE 12207
standard. On its website the IEEE Professional Communications Society (PCS) has not
addressed the documentation development life cycle.9 Neither does the PCS seem to
have any plans to address how to organize document suites according to a life cycle,
styled after the software development cycle.10 A search in Google for the PCS
transactions for Documentation and Document Development Life Cycle yields

Technical writing as an evolving discipline

Page 3 of 16

The Association for Computing Machinery (ACM) has a documentation cycle interest
group, but no progress towards completing a standard is apparent. A substantial article
was published (discussed, below) comparing documentation system life cycle
development to the Rational Unified Process (RUP).12 The SEI has its Software Body of
Knowledge, comparable to the Project Management Body of Knowledge by the Project
Management Institute and there is the Capability Maturity Model, but, neither has a
DSDLC as is evidenced by the SEI website.13


Software development process formalization commenced in earnest during the mid to late
1980s, known better now as software engineering. Indeed, Carnegie-Mellons
Software Engineering Institute (SEI) is devoted entirely to this field. Other
organizations, such as the Rational Corporation have created the Rational Unified Process
(RUP), along with automated tools, to collect information necessary and supportive of a
software development effort and organized it into a coherent, effective structure to drive
projects. Coupled with this is a developers tool, the Uniform Modeling Language
(UML) that, from a software developers point of view, presents an ongoing description
of the software development cycle in a project.15 The UML is an outcome of Rational
Software and is the core of sophisticated, proprietary, and often expensive software
applications. While the UML may be considered a successful engineering practice, one
should bear in mind that there may be substantial critiques and limitations, not the least of
which is whether the method is appropriate for all sizes of software development projects
and whether the UML approach is sufficiently scalable. It seems that undue attention has
been paid to business environments by software tool developers. It is critical to bear in
mind that there are other environments out there as well, including scientific,
governmental, and educational arenas, whose needs are not always compatible with those
of business.
This essay is not designed to critique the UML but to state that current documentation
systems analysis must be prepared to address other methodologies. The UML description
can be quite extensive, and not all projects require the rendition of the vast amount of
detail offered by Rational Rose or other tools. This does not minimize the importance of
capturing the essential elements in a UML analysis. While the RUP is a useful bridge
between support documentation and the UML, many RUP categories do not correspond
with other support documentation, such as user guides and acquisition documents.
However, the RUP, like the UML, does emphasize that software development is a
dynamic and re-iterative process, suggesting that documentation must follow in the same
way. Further, the document structure should accommodate minimum maintenance
requirements, usually accomplished by techniques like hyperlinks to a core information
set or database. Both the UML and RUP imply that the documents should cohere in the
same manner as software development. The RUP development tools provide document
templates for software development information; however, there is not the explicit
formalization of interrelating documents, themselves. Technical writers have leeway
with RUP in creating user guides and other end-user support material, but there is no
explanation of how these materials should be formally integrated into the document set.

Technical writing as an evolving discipline

Page 4 of 16


Software development information is conveyed by categories, such as requirements,
design specifications, and code, as outlined in the IEEE 12207 standard. Support
documentation contains contract information, deliverables lists, schedules, environmental
requirements, administrative details, and information needed by non-developers involved
with the project. Support documentation also includes guides (user, administration,
installation, and trouble shooting), training manuals, reporting and evaluation systems,
and status reviews.
The SEI claims that most projects are in an ad hoc or a beginning stage of a mature
development process;16 the Y2K debate highlighted this issue. Whether ad hoc was
sufficient to solve the Y2K problems or whether organizations matured rapidly enough
to do so will be a matter of controversy for some time to come, but evidence suggests that
the more organized a project, the greater chance for its success. Leading software
development critique Edward Yourdon17 stated in 1997 that the majority of projects fail
or fall behind schedule due to the lack of a formalized process. From 1995 to 1998, the
Institute for Electrical and Electronics Engineers (IEEE) issued a three-part standard,
IEEE/ISO 12207, for the software life cycle, which forms the basis of the DSDLC
standard presented in this paper. The following formalized process organizes
documentation into a system that completely captures the life cycle development.
Ideally, the contents of this system should enable any outside person to continue the
project where a previous team left off.
Organization is essential for a successful documentation effort. Standard phases of my
document life cycle include:

Needs and audience assessment

Establishing revision control
Gathering of raw information from developers
Creating first document draft
Collective review by developers and writer
Distributing and archiving of document.

However, like software development phases, these phases can be formalized. The
DSDLC can be modeled after the RUP. The RUP, according to Priestley, says:
The software development process must be articulated and adopted.
A documentation development process must be articulated and adopted.

Technical writing as an evolving discipline

Page 5 of 16

The documentation group's involvement in the software process must start at the
beginning; many of the integration points identified occur in early phases of the
The documentation and software development groups must share ownership of
key documents, in particular the glossary and use cases. (Priestley, Ref. No. 11)
These phases were described in a paper by Michael Priestley, A Unified Process for
Software and Documentation Development, and amply describe the details of how a
documentation development life cycle might appear. He adds Information Architect as
a new worker and delineates the activities and artifacts. The documentation process as a
workflow is compared to the software workflow. There is a mapping of the
documentation development life cycle to the elements of the RUP, and these steps appear
to capture most, if not all of the essential elements of the DDLC. While, it is not a
purpose of this paper to outline a proprietary treatment of information conveyance, it is
worthwhile to refer to Priestleys discussion as a model on which to build further
processes, as it evolves into the creation of a formal model patterned after software
development lifecycle standards, in particular, towards the IEEE 12207 and SEI
Another documentation systems development model by Joann T. Hackos has been
circulated and is used widely in courses on technical writing. Documentation is prepared
in terms of more general considerations, such as project needs assessment, organizational
constraints, and end user requirements. In Managing Your Documentation Projects18,
Hackos presents a process model that assesses the organization and its resources for
preparing documents. This process model analyzes the documentation objectives, the
audience needs, publications tools, review and testing, user acceptance, and maintenance.
Project evaluation and process improvement finalize her documentation life cycle. In the
Appendix of her work Hackos gives templates and checklists for establishing a
documentation life cycle. The Information Plan Template includes project purpose and
documentation, description of the product being documented, audience profile, the
activities to be performed, documentation production mechanics, restrictions, and review.
Her Audience-Analysis Checklist focuses upon the character of the audience, such as
language, attitudes, and educational level. The Environment-Analysis Checklist asks
about the reason for documentation, where it will be done, staffing, available resources,
and distribution. As to the document content, there are provisions for publication goals
and objectives, audience profile, usability testing, organization doing the publishing, and
publication content. (Hackos)
It is to be noted, however, that while there are certain essential items in the templates,
such as testing in the Content-Specifications Template, there are no separate templates
for those items. Testing is such a critical area, and there should be special attention paid
to it. Within the testing arena are numerous sub-areas, including usability testing, unit
testing (each document tested by itself), integration testing (consistent formats across all
documents, hyperlink integrity, etc.), and acceptance testing (what the recipient of the
final document wants and expects). A master test plan would be an approach to
addressing the vast amount of issues in this domain. It is not the intent of this paper to
Technical writing as an evolving discipline

Page 6 of 16

criticize Hackos efforts, but to incorporate her excellent work in developing methods
and guidelines.


A primary issue in standardization is ascertaining the model to be followed in developing
documents. It is tempting simply to adopt a proprietary process, such as Rationale Rose,
RUP, or an independently created model, but it is more objective to treat document
development independent of existing models. Hackos provides a substantial platform on
which to build the criteria for documentation standard. A non-proprietary standard can
formalize document systems analysis with unbiased evaluation criteria emerging from a
peer-reviewed process. For example, her templates can provide the basis for a DDLC
standard. However, a standard is meant to provide guidelines, not content specification.
That is, one should consider how to determine the content of a documentation systems
development life cycle, the standard offering a model approach.
How, then, can one organize the document development life cycle? By incorporating the
best practices of documentation research groups and standardization organizations. A
substantial beginning is looking at well-developed models, such as those presented by
Hackos, Priestley, the RUP, and UML.

The IEEE serves as a starting point, as it appears to be the most flexible in being
compatible with a wide range of proprietary considerations and best practices.
Furthermore, 1) It is the only international software development standard (or basis of
any other international documentation systems development standard) and, 2) the
standard is generic, not being dependent upon any proprietary software development
methodology. The United States military has adopted IEEE 12207, thus assuring that the
standard will have substantial support. Accepting an IEEE-based documentation
standard may set the stage for a generic documentation standard that manufacturers,
financial institutions, and others may follow.
However, adopting the IEEE 12207 as a basis for a documentation system life cycle does
not guarantee its universal acceptance. Two major issues face a proposed documentation
standard: 1) detailing the stages and its content, and 2) getting people to adopt and use it.
The IEEE has an extensive process of garnering input from many parts of the computer
community. People may become members of the IEEE and, after attending a certain
number of plenary sessions, can become voting members of working groups. On the
outside, non-members can participate in voting for standards. Of course, organizational
squabbling occurs, the bones of contention often being proprietary interests, but there
usually is an overarching realization that standardization ultimately makes life easier for
all. For processes, such as software development, people accept that an organized effort
is potentially far more successful than an ad hoc one. Recognizing that documentation
has just as much importance as the software (or other) development and the need to
formalize it within an already accepted model will be the major impetus for presenting
documentation in its own right as software development has done.

Technical writing as an evolving discipline

Page 7 of 16

Documentation Framed by IEEE 12207

The IEEE/ISO standards lists the following documentation processes:


Distributed among the categories of:

Process implementation
Design and development

However, there are many gaps, as the following discussion shows.

I outline IEEE 12207 documentation categories and examples of content specification
guidelines, parallel to the ones in the software development cycle. While the lists of
categories and their issues and activities are self-descriptive, they may accommodate a
fuller description, similar to the detailed discussion of guidelines in the 12207 standard.
For now, it is enough to refer to the descriptions in the IEEE standard for the basis of a
detailed description of a documentation standard. The outline is not exhaustive but is
meant only to be illustrative of the conceptualization of the DDLC. While the DDLC is
presented as a series of steps or stages, it should be kept in mind that the life cycle is
iterative; it is not meant to be a waterfall or spiral process model. Re-iteration
characterizes documentation systems development as a dynamic process, a feature that
makes the RUP a powerful software development method.

The Documentation Development Plan Rationale What you

are going to do Similar to SDP

Purpose of documentation and audience

Method of assessing requirements
Development tools publication software, computer systems
Description of document set
Team policies and procedures
Documentation method
Constraints and dependencies
Document testing issues

Technical writing as an evolving discipline

Page 8 of 16

Configuration management

Configuration Management How documents are managed

Naming and numbering

Revision control
Change modification
Release management and delivery

Example issues:

Documents having different version numbers than software development version

Hyperlinking for minimizing document maintenance
Smart Codes document number contains descriptive code

Process Implementation Need for verification effort

Necessity of useful and accurate documentation

Document activities to be verified

Documentation verification methods way of demonstrating that process has
been implemented

Technical writing as an evolving discipline

Page 9 of 16

Assess customer needs and wants (e.g., surveys)

Audience needs
Documentation development environment publication tools, styles, formats
Quality assurance
Tracking requirements
Process for assessing document development cycle
Precedence and criticality of requirements
Scalability of DDC how much detail is required
NOTE:IEEE 12207 discusses system and software requirements and matching
architecture. One might, in very large projects, describe documentation in the
context of the software and organization.

Document Architecture
Actors/audience Users Developers, managers, end users

Components types of documents in set

Relationship of documents to each other and their environment (software,
organization, audience, etc.)
How the document will meet the requirements, as outline above


Guides installation, user, administration, trouble-shooting

IEEE 12207 document set requirements, architecture, testing
Team policies and procedures
Document flow configuration management, stages of document development
Interrelationships of documents high-level discussion of document content
Revision control and archiving
Document classification and numbering

Technical writing as an evolving discipline

Page 10 of 16

Document Design Analogous to software design

Templates Arrangement, format

Writing style
Content description what goes in each document
Style guides
Naming and numbering system and conventions
Distribution medium as it affects design (e.g.: Web-based documents affect
How architecture will be implemented

Testing and Quality Assurance

Documents must be edited for grammar (criteria listed toward the beginning of this
paper) and tested for content accuracy and usability. As long as the end user successfully
accomplishes the tasks described, the documentation has served its purpose. Each project
requires its own list of items to be tested, but several considerations are common:

Standards criteria knowing whether the document works

Meeting customer requirements, specified in the Document Development Plan,
Document Requirements, and acquisition documents
Setting for types of testing: user, acceptance, quality, integration
Establishing a testing method individual, group, peer, etc.
User evaluation standards and reporting

Integration Interrelating documents and process

Hyperlinking documents to each other and to outside sources

Indexing gateway to document set, accompanied by navigation tools
Consistency checking style, format, accuracy (based on testing)

Customer acceptance will be according to Government satisfaction, DoD requirements,
quality assurance standards, and acquisition criteria.

Archiving web-based, hard copies, binding

Delivery method
ISO 9000 and other standards compliance, when applicable

Technical writing as an evolving discipline

Page 11 of 16

The previous steps act as a context for evaluating successive points in development, thus
allowing an alteration of the whole documentation development plan.
In the same manner that the IEEE 12207 accommodates the RUP (or any other
proprietary model) for software development, so the above descriptive categories can do
the same for an RUP rendition of the documentation process (as in Annex A of ISO

A Larger Environment
However well defined the documentation systems development life cycle may be, there
must be integration with its context. For example, a proprietary system development may
not be compatible with policies and procedures of an organization. A documentation
process might not be scaled properly to the needs and size of the project and the
capability of the organization to support it. The process, itself, must be evaluated for
The IEEE 12207 software development life cycle has been selected as a documentation
model for non-proprietary issues partly because the U.S. military has adopted it as a
standard. A non-proprietary scheme with the same backing is the Capability Maturity
Model (CMM). The CMM defines these levels of formalization in the software
development process as:
1) Initial. The software process is characterized as ad hoc, and occasionally even
chaotic. Few processes are defined, and success depends on individual effort and
2) Repeatable. Basic project management processes are established to track cost,
schedule, and functionality. The necessary process discipline is in place to repeat
earlier successes on projects with similar applications.
3) Defined. The software process for both management and engineering activities
is documented, standardized, and integrated into a standard software process for
the organization. All projects use an approved, tailored version of the
organization's standard software process for developing and maintaining software.
4) Managed. Detailed measures of the software process and product quality are
collected. Both the software process and products are quantitatively understood
and controlled.
5) Optimizing. Continuous process improvement is enabled by quantitative
feedback from the process and from piloting innovative ideas and technologies.

Technical writing as an evolving discipline

Page 12 of 16


It is instructive to compare these levels to those presented by Hackos with respect to the
maturity documentation processes. She explains six levels:
Oblivious There is no perceived need for documentation, and what there is of it is
produced dependent upon in-house resources. Hiring technical writers sets the stage for
the next level of maturity.
Ad Hoc Technical writers prepare documents independently, with little or no
coordination. A style guide evidences evolution to more sophisticated processes.
Rudimentary Some coordination exists among the writers, and that some project
planning exists heralds the next stage of maturity.
Organized and Repeatable There is the beginning of a well-established
documentation development process, and training exists for the writers. To advance to a
higher stage, there is project planning.
Managed and Sustainable Project management, estimating and tracking projects, and
budgeting characterize this stage of documentation process maturity. Further work on
strengthening processes indicates that documentation is ready for the next and last stage.
Optimizing Persistent monitoring of processes and efforts to improve the process are
found in conjunction with the emergence of self-managed teams. These properties are
found in an organization that is committed to sustaining this level of maturity.20
In essence, the concept of both CMM and the Documentation Process Maturity Model
(DPMM) are alike in that both models describe the formalization of processes.

Beyond CMM and DPMM

Technical writing has grown from an exercise in describing a process or product to a
much larger discipline of knowledge management, of which technical writing is but a
part. This is because research, writing, and distribution of information occur in a context,
and that context, itself, needs a defined process. It is difficult to imagine how one could
argue that documentation could be treated as an isolated process or that describing that
process could ignore how it interrelates to the environment.
The U.S. Department of Defense (DoD) recognized the need to make specific aspects of
software development and the documents describing it (in the Data Item Descriptions) fit
into the generalized model of IEEE 12207. Software development needed a description
of how it would be treated in terms of its environment, the CMM being a beginning in
fulfilling that need. CMM-I is the ongoing framework for describing the environment.

Technical writing as an evolving discipline

Page 13 of 16

Knowledge management extends beyond the software domain. Traditionally, it has been
regarded as overhead, not yielding immediate material return. Two disciplines, one
more immediately relevant to our discussion than the second, appear on the horizon as
areas into which information development and distribution can fit. They are knowledge
management and information science.
How both natural and artificial knowledge can be optimized for business settings
enter in the form of a certification program to which the DoD subscribes. (Knowledge
Economics, and Economics-based Knowledge Management Certification Training
Program of the Global Economics Knowledge Council).21 This certification in
knowledge management has proprietary tracks:
Certified Knowledge Manager (CKM) focuses on knowledge and innovation
economics from the point of view of a manager or executive, and the Certified
Knowledge Economist program includes: Economics of Knowledge and Innovation
natural knowledge processes of the organization and how to identify, model, measure,
and manage those processes.
Information and Communications Technology integration of knowledge and
activity across content domains, space, time, and people. Participants particularly focus
on accelerating the creation and dissemination of new knowledge in groups,
organizations, businesses, and scientific communities.
A second discipline is information science, a mature outgrowth of library science, and, in
turn a development from librarian. This discipline in years past meant the ability to
retrieve information from card catalogues but now includes research, preparation, and
dissemination of information.22 These areas are expected to develop into more
formalized disciplines to encompass information management.

Technical writing is common in many community colleges across the
United States.23 It is but a relatively small part of the large environment of
information management. Further research and development in language
systems and artificial intelligence suggest that the devices and methods of
retrieving, processing, and synthesizing information in order to interrelate
with beings of every kind may be regarded as extensions of our own
brains (in the case of devices) and minds (in the case of methods). The
nature of methods is reflected in terms of the devices, and nature of the
devices is reflected in terms of the methods. We can now talk about
evolving technical communication, as it has evolved before and is bound
to be.

Technical writing as an evolving discipline

Page 14 of 16

1. IEEE/EIA 12207, Software lifecycle processes (Numbers 0-2, 1996-1997)
3. For example, the following website takes this approach: - development
of individual document
8. ,,_Pawan
12. Michael Priestley and Mary Hunter Utt, A Unified Process for Software and
Documentation Development (IEEE document number 0-7803-6431. (2000)
15. For example, see:

16. Lewis Gray, IEEE12207CMM9001.pdf

17. Yourdon, Edward and Jennifer (1998) Time Bomb 2000. New Jersey: PrenticeHall. Pp. 358-386
18. JoAnn Hackos, Managing Your Documentation Projects. New York: John Wiley
& Sons, Inc. (1994). See also: .
20. Hackos, p. 47
22. For example,
23. See as a paradigm.

Jeremy Horne, PhD., Director, Compliance and Standards Division,

Taylor Technical Publications & Consultants, Inc., Scottsdale, AZ

Technical writing as an evolving discipline

Page 15 of 16

Consultant, RhinoCorps, Ltd. White Sands (NM) Missile Range
Janette S. Taylor, President,
Taylor Technical Publications & Consultants, Inc., Scottsdale, AZ

Technical writing as an evolving discipline

Page 16 of 16