April 2016
By Annette D. Reilly

Image: @MistikaS/istockphoto.com

Annette Reilly, Ph.D., CSDP, CSEP, PMP, has led the development and harmonization of IEEE and ISO/IEC standards for systems and software engineering, software user documentation, and IT service management for over 15 years. She retired as a senior staff member from Lockheed Martin, where she held a variety of responsibilities for proposal management, engineering management, systems engineering, information management, and technical documentation.


annette.reilly[at]computer.org
www.scriptorium.com


 


 

Note: A longer German version of this article appears in Anthology on Technical Communication, ed. Jörg Hennig and Marita Tjarks-Sobhani Vol. 20: Gesetze, Urteile, Normen, Richtlinien, Regelungen für die Technische Kommunikation, Stuttgart: tcworld, 2015. ISBN 978-3-944449-39-5.

Standards for software documentation

Standards can greatly assist technical writers, documentation managers, designers and developers. But which standard applies to which team member and which ones are most useful in software documentation?

Standards for software documentation are important tools for technical writers. They provide content creators with the requirements for information products and guide them through the process of developing such products. They ensure that the information content, structure and format are suitable for the intended audience. And they can help other stakeholders concerned with software processes, including software users.

This article is intended to help content creators evaluate, select, and apply appropriate standards. It focuses on international standards from ISO, IEC, and IEEE.

Why we need standards

Software providers want their products to be usable. Usability is the "extent to which a system, product or service can be used by specified users to achieve specified goals with effectiveness, efficiency and satisfaction in a specified context of use" (ISO/IEC 25064:2013).

Software users consult documentation in three main modes:

  • Conceptual: to help understand goals, principles and methods involved in completing a process or task
  • Instruction: to learn how to complete a procedure
  • Reference: to search for details when something has been forgotten or when something unexpected happens (troubleshooting).

Thus, software providers have an obligation to warn users when the software might create hazardous conditions, and to advise users when incorrect use of the software could result in unsatisfactory results. Software user documentation standards such as ISO/IEC 26514:2008, Systems and software engineering – Requirements for designers and developers of user documentation, and ISO/IEC/IEEE 82079-1 (in revision), Information technology: Information for use of products – Part 1: General requirements and processes, explain how to do this in a consistent and useful way.

Just as software and its user documentation should be aligned with the needs of its audiences, a set of standards for software user documentation, numbered ISO/IEC/IEEE 2651N, is aligned with the needs of those involved in documentation (Figure 1).

ISO/IEC/IEEE Standard number

Relation to user documentation

26511

Managers

26512

Suppliers and acquirers

26513

Editors, reviewers, testers, and assessors

26514

Designers and developers (writers and illustrators)

26515

Agile team members

Figure 1: Audience-oriented standards for software user documentation

Standards for designers and developers

ISO/IEC 26514:2008 is the most extensive standard for the design and development of user documentation. It covers both the process and the documentation product (content, structure, and format), and includes an annex on the content of style guides and another on writing style and techniques in English. The process sections include analysis of audience profiles, tasks, and usability goals and objectives, with some coverage of life-cycle management.

Review tasks are treated in more detail in ISO/IEC/IEEE 26511:2012, Systems and software engineering – Requirements for managers of user documentation, and ISO/IEC 26513:2009, Systems and software engineering – Requirements for testers and reviewers of user documentation.

ISO/IEC/IEEE 26514 considers audience analysis as part of documentation design (choosing which functions need to be documented for which categories of users when developing a documentation set).

Sections on the structure of documentation describe where to appropriately place information and critical information such as warnings. They specify document components such as package label or title page, table of contents, concept of operations, procedures, error messages and problem resolution, navigational features, index and search capability.

Content of software documentation is tied to fulfilling data quality characteristics of completeness and accuracy. Sections on the information content allow for minimalist approaches while making sure that all critical software functions are covered in the documentation ("software whose failure could have an impact on safety, or could cause large financial or social loss"). Detailed requirements for the content and structure of procedures (instructions) reflect their importance for software documentation users. The standard also includes requirements for the content of error messages and warnings (critical safety information).

Regarding format, 26514 discusses the choice of appropriate printed or electronic media. For example, certain topics (such as software installation) are required to be available in printed form separate from the software. It also covers formats for illustrations and page design.

ISO/IEC/IEEE 26515: 2011
, Systems and software engineering – Developing user documentation in an agile environment, considers the challenges for information developers when they participate in one or more agile teams. As team members, they can contribute to several tasks along with designing and developing user documentation, such as recording development plans and user stories, contributing to GUI design, managing changes to requirements, leading or performing usability testing, and tracking progress during sprints. This standard recommends that documentation be complete and tested before a sprint is closed.

Websites can provide quick access to information, an accessible way to acquire and evaluate knowledge and concepts, and a way to share information and opinions among a user community. ISO/IEC/IEEE 23026:2015, Systems and software engineering – Engineering and management of websites for systems, software, and services information, is intended to improve the usability of technical information provided in a website. It includes requirements for the processes of strategy and planning, designing, engineering, evaluating and testing, and sustaining websites for technical information. Website management considers the lifespan of the website and its information, configuration control, and estimation of resources for site sustainment.

Website design strategy focuses on the separation of content and presentation, use of consistent design, separation of marketing and information, choice of multimedia, performance concerns, and special considerations for website translation and localization. Requirements for search functions and site navigation and privacy policies are emphasized, including protecting the security of the website's technical information, user data, and IT resources. (The ISO/IEC 27000 series has the primary standards for information assurance.)

Documentation for software organizations and projects

Standardized information about software life-cycle processes and products helps organizations plan strategically, control their results, inform their stakeholders, and streamline their processes, with the goal of improving their software products.

ISO/IEC/IEEE 15289:2015, Systems and software engineering – Content of life-cycle information products (documentation), is the primary standard for life-cycle documentation (information items). It specifies the content of information items from several perspectives:

  • Purpose and common content for typical information items (generic types)
  • Specific content needed for various life-cycle processes
  • Types of data to collect as records in data stores and use in documents

The generic types are identified as policies, plans, procedures, descriptions, specifications, requests, and reports. In theory, it would be possible to prepare each of these types of document for each process used in a project. In practice, the specific information items produced for a project should be limited to those needed by stakeholders, with information reused and repurposed throughout a software portfolio. Thus, 15289 does not prescribe the title, format, structure or exact content of specific information items, as long as the required content is available in some way.

ISO/IEC 26513:2009 (currently in revision) covers the methods for improving the quality of software user documentation, primarily reviews and testing. It emphasizes planning for reviews for different purposes (such as technical accuracy or editorial correctness) at different points in the software and documentation life cycle. It describes managing the output of reviews, and resolving problems discovered during reviews and tests. It describes various purposes for testing documentation, including a system test for consistency between the software performance and the documentation, tests of accessibility and localization, and usability testing.

Information management and content management standards

Basic requirements for the purpose and outcomes of the information management process (including documentation management) are found in ISO/IEC/IEEE 15288:2015, Systems and software engineering – System life cycle processes, and ISO/IEC/IEEE 12207, Systems and software engineering – Software life cycle processes (new 2016 edition in preparation): "The purpose of the information management process is to generate, obtain, confirm, transform, retain, retrieve, disseminate and dispose of information, to designated stakeholders."

Specialized standards provide more information on how to manage documentation and content, and how to acquire documentation products and services.

ISO/IEC/IEEE 26511 is applicable to managers of both software and systems user documentation. It covers organizing and planning for an ongoing workflow and documentation portfolio, including developing a team with specific roles, obtaining infrastructure resources, and establishing management control through measurement. It briefly describes the vexing concern of estimating resources for documentation projects. It suggests measurements of documentation products, productivity, quality, and measures for process improvement, and includes suggestions to minimize the cost and improve the quality of translations. It includes requirements for a user documentation management plan and a documentation plan.

ISO/IEC/IEEE 26531:2015, Systems and software engineering – Content management for product lifecycle, user, and service management documentation, aids in developing a content management strategy, preparing a business case for content management, defining the content management workflow, and selecting the needed content management system (CMS) functions: defining an information model for structured authoring, developing authoring guidelines, deciding on the content sustainment and reuse strategy, and implementing quality management through content review and approval. It includes specific requirements for a component CMS: repository management, content object management, system administration, authoring, workflow control, output for publication, management of localization and translation, and system interoperability.

ISO/IEC/IEEE 26512:2011
, Systems and software engineering – Requirements for acquirers and suppliers of user documentation, deals with the agreement processes of acquiring and supplying documentation products and services, from the point of view of the acquirer (customer) and the supplier (contractor for outsourcing). It can be applied within an organization as well as for external suppliers. It covers what to include in a request for proposals (request for tender) and in a proposal, as well as monitoring and managing the agreement and handling changes that arise during the work. It details what needs to be defined in requirements for user documentation and in a user documentation specification and statement of work.