Professional Documents
Culture Documents
Synopsis:
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).
THE ISSUE
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.
Page 1 of 16
Overall appearance
Completeness
Technical accuracy
Language mechanics
Readability
Quality and relevance of illustrations
Usability
Cover page
Title page
Table of Contents
Approval information
ISO-compliant revision tracking
Proprietary statement (when necessary)
Body
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.
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.)
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
Page 4 of 16
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.
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
process.
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
standards.
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.
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.
Page 7 of 16
Planning
Designing
Developing
Producing
Editing
Distributing
Maintaining
Process implementation
Design and development
Production
Maintenance
Page 8 of 16
Configuration management
Resources
Deliverables
Example issues:
Page 9 of 16
Requirements
Assess customer needs and wants (e.g., surveys)
Audience needs
Documentation development environment publication tools, styles, formats
Resources
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
Examples:
Page 10 of 16
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
design)
How architecture will be implemented
Deployment
Customer acceptance will be according to Government satisfaction, DoD requirements,
quality assurance standards, and acquisition criteria.
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
15504).
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
efficacy.
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
heroics.
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.
Page 12 of 16
19
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.
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.
Afterword
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.
Page 14 of 16
References
1. IEEE/EIA 12207, Software lifecycle processes (Numbers 0-2, 1996-1997)
2. http://www.pmi.org/info/default.asp
3. For example, the following website takes this approach:
http://www.cehandbook.com/ziegler/tpubsweb/techpubs/how.html - development
of individual document
4. http://www.ttsystemsinc.com/PM/document_life_cycle.htm
5.
http://www.stcsig.org/quality/shared_documents/CMMI_Proj_Doc_Model_L2.jp
g
6. http://stcrmc.org/Samples_and_Templates/SamplesTemplates.htm
7. http://www.ieeepcs.org/
8. http://www.stc-india.org/Conf_2001/pawan_nayar.ppt ,
http://tc.eserver.org/authors/Nayar,_Pawan
9. www.ieeepcs.org/
10. www.ieeepcs.org/plan_acgt.pdf
11. www.ieeepcs.org/transactions/search.cgi
12. Michael Priestley and Mary Hunter Utt, A Unified Process for Software and
Documentation Development (IEEE document number 0-7803-6431. (2000)
13. www.sei.cmu.edu
14. http://www.storybridge.com.au/Testing/BasicConcepts.htm
15. For example, see:
www.rational.com/uml/index.jsp
www.omg.org/uml/
www.uml.org/
Page 15 of 16
and
Consultant, RhinoCorps, Ltd. White Sands (NM) Missile Range
Janette S. Taylor, President,
Taylor Technical Publications & Consultants, Inc., Scottsdale, AZ
***
Page 16 of 16