Audience-Oriented Standards for Software Documentation from ISO

By Annette Reilly | Fellow

With major contributions from STC members, a consistent set of software documentation standards is being released. These international standards from ISO (International Organization for Standardization) are keyed to the needs of specific audiences (see Table 1).

Table 1. Audience-oriented ISO/IEC/IEEE standards for software documentation

The new 2651N series of ISO software documentation standards addresses both the product (user documentation) as well as the process. These standards are aimed at technical communicators in multiple roles who want to use well-understood, repeatable processes and improve their processes. These standards are media-independent—they work for both electronic and print documentation. They are independent of vendor tools and technology for authoring, content management, or delivery systems. While they are consistent with the use of CMMI® process improvement or protocols like XML or DITA, they do not require application of specific protocols or metadata schema. These standards can be applied by large organizations and lone writers.

Why standardize user documentation products and processes?

User documentation can be specified in terms of structure, format, and content. Having a standardized, consistent structure and format for user documentation should make the documentation easier to develop and more usable. Using and reusing content has significant cost advantages for documenting multiple platforms, products, and translated or localized versions of content.

Standards take the benefits of consistent products beyond a single organization, by establishing an internationally recognized set of requirements for an acceptable level of software documentation. Using a standard means that documentation producers and customers have a consistent accepted reference for the format and content that they will find in the documentation. For example, what documentation must be printed? What does it mean to say that the documentation is “complete”? Does it have to include every function and screen shot? These ISO standards balance affordable, minimalist documentation with the interest of software users in consistent, complete, accurate, and usable documentation. ISO/IEC/IEEE 26514 requires:

“Documentation shall provide complete instructional and reference information for all critical software functions (software whose failure could have an impact on safety, or could cause large financial or social loss). Instructional mode documentation shall include complete information to enable performance of selected tasks using the software functions by the least experienced members of the audience. Reference mode documentation shall include all instances of the selected elements being documented. For example, if reference mode documentation covers a subset of software commands, it shall include the relevant user-entered and system-displayed commands and error messages in that subset.” (11.1)

Using a standard does not guarantee that a superlative piece of work will be produced, but it does give you, your manager, and your customers assurance that the documentation will have at least a mutually accepted and effective set of features.

Beyond standardizing the documentation products, standardizing the documentation and information management process offers significant advantages when moving beyond a single project to developing and updating multiple concurrent projects, versions, and languages. The 2651N series emphasizes the use of consistent, repeatable processes and the “Plan-Do-Check-Act” quality cycle. They recommend best practices for documentation planning, audience- and task-analysis activities, along with editorial reviews and testing. They apply to documentation developed concurrently with the software as well as to separate documentation for existing software. Repeatable, standardized processes can make estimates more accurate and understandable to managers and customers, and make documentation more affordable.

What’s covered in the ISO software documentation standards?

ISO/IEC/IEEE 26514:2008, Systems and software engineering—Requirements for designers and developers of user documentation, 143 pp. This comprehensive and detailed work is both a process and a product standard. 26514 presents requirements for the user documentation process within the systems or software life cycle, emphasizing understanding of the project goals and constraints, and detailed audience and task analysis as the basis for documentation design. It addresses documentation structure for task-oriented or quick reference information; requirements for the completeness and accuracy of information; and handling critical information such as warnings. It provides an extensive discussion of formats for printed and online text and graphics in documentation. Annexes cover writing style and techniques for English-language documentation, including style for translation. Checklists for user documentation are based on STC competition evaluation forms. Co-editors of 26514 were STC Fellows George Hayhoe and Annette Reilly.

ISO/IEC/IEEE 26513:2009, Software and systems engineering—Requirements for testers and reviewers of user documentation, 53 pp. This standard covers the activities and responsibilities for planning and conducting documentation reviews and managing the results of the review. It also addresses how to plan, measure, and conduct usability tests for documentation, along with tests of accessibility and of localized or customized versions. STC members were reviewers and contributors to the drafts of 26513.

ISO/IEC/IEEE 26512, Software and systems engineering—Requirements for acquirers and suppliers of user documentation (pending publication in 2011), 37 pp. This new standard lays out the processes for acquiring user documentation services and for monitoring and managing contractors. It also covers the contractor’s activities, such as evaluating opportunities, preparing proposals, and reaching agreement on a contract. It includes the contents for an acquisition plan, user documentation specifications, the statement of work, a model request for proposal for user documentation products or services, and the resulting proposal. STC Fellow Ralph Robinson was the editor of 26512.

P26511, Software and systems engineering—Requirements for managers of user documentation (in ballot, expected publication early 2012), approximately 43 pp. This draft standard considers documentation management as part of portfolio and content management. It covers preparing an overall documentation management plan as well as plans for specific documentation sets. It includes sample role descriptions for those on the documentation team. It discusses measuring and estimating documentation work and applying management control to documentation, including change control, schedule and cost control, resource management, and communication. STC members are reviewers and major contributors to the drafts of 26511.

P26515, Software and systems engineering—Developing user documentation in an agile environment (in ballot, expected publication early 2012), approximately 30 pp. This draft standard considers the special features of Agile development projects that pose challenges for managing and developing documentation, such as managing change, including information developers on Agile teams, completing documentation tasks that extend across sprints, sizing and estimating for each sprint, and integrating documentation test and review with software development and test. STC members are reviewers and contributors to the drafts of 26515.

P15289, Software and Systems Engineering—Content of life-cycle information products (documentation) (in ballot, expected publication late 2011), approximately 83 pp. 15289 is primarily for information planners and managers whose software and systems projects and organizations have a medium-to-high level of process maturity. This standard covers the information and records to be managed throughout the life cycle of a software or systems project, such as the program management plan, problem records, software architecture description, integration and test plans, and concept of operation. It also addresses the documentation required by those managing IT services through ISO/IEC 20000-1, such as the service level agreement, release plan, and information security plan. It identifies the content of documents (information items) required for each life-cycle process and service. Documents are described as instances of generic types (such as plans, reports, procedures) with generic content (such as purpose statement, glossary, and index) as well as their specific content. The flexible approach of 15289 permits combining or subdividing the 88 information items (documents) it identifies without using its exact nomenclature. The required content can be included by reference to another document. This is a revision of ISO/IEC 15289:2006 to reflect updated versions of the life-cycle standards and to include ITSM-service management documentation. The editor of 15289 is STC Fellow Annette Reilly.

How can I participate in standards projects?

A first step is to advocate in your workplace for the use of documented, repeatable processes; consistent styles, templates, and formats; information reuse; and content management. You can find requirements and examples in ISO/IEC/IEEE standards. If you are interested in reviewing or editing draft ISO or IEEE software documentation standards and contributing to standards development, contact the standards editors named in this article. Conformance to ISO and IEEE standards is voluntary, although standards may be required by contracts. There are currently neither organizational nor individual certification bodies to validate compliance with these ISO standards.

Most of the guidance in ISO software documentation standards comes from the best practices and guidance developed by leading STC members in books, journal articles, STC Summit presentations, as well as from international working group members. ISO standards follow a process like most documentation projects, from approval of a proposal, development of working drafts, review and ballot, resolution of comments, and re-ballot until a consensus is reached. ISO and IEEE take responsibility for publishing and marketing. Standards have periodic reviews and may be updated, withdrawn, or stabilized after five years of use.

Where can I get copies of ISO standards?

Over 100 member bodies support ISO standards development. You can purchase standards directly for download or hard-copy delivery from ISO or the national standards organizations listed in Table 2. Also, the ISO software documentation standards were either jointly developed with or subsequently adopted by the IEEE Standards Association and may be purchased from IEEE.

Table 2. Some sources of ISO software documentation standards

Some standards are freely available. For example, the Systems and Software Engineering Vocabulary (to be published as ISO/IEC/IEEE 24765) contains all the terms and definitions from the ISO software documentation standards described in this article. You can search for terms or download the entire vocabulary at www.computer.org/sevocab.

Annette Reilly (annette.d.reilly@lmco.com), PhD, is an STC Fellow and chair of the STC Standards Council. She is STC’s primary representative to, and chair of, the ISO/IEC JTC 1/SC7 U.S. Technical Advisory Group. She works as a proposal manager for Lockheed Martin.