ISO/IEC JTC 1/SC 7/WG 2 - System software documentation

This document specifies requirements for efficient development and management of information produced — throughout the life cycle of a system and software product; — for the provision of information for users of systems and software; — for the management of IT and support services. This document is independent of the tools, protocols, and systems used for content management. It does not address configuration management of software assets. The content management process presented in Clauses 6 to 10 is a specialization (lower-level process) of the information management process specified in ISO/IEC/IEEE 15288 and ISO/IEC/IEEE 12207.

This document covers the development process for designers and developers of information for users of software. It describes how to establish what information users need, how to determine the way in which that information should be presented, and how to prepare the information and make it available. It is not limited to the design and development stage of the life cycle, but includes information on design throughout the life cycle, such as design strategy and maintaining a design. This document provides requirements for the structure, information content, and format of information for users of software. This document can be applied to developing the following types of information, although it does not cover all aspects of them: — information for users of products other than software; — multimedia systems using animation, video, and sound; — computer-based training (CBT) packages and specialized course materials intended primarily for use in formal training programs; — maintenance information describing the internal operation of systems software; — information for users incorporated into the user interface itself. This document is applicable to information architects and information developers, including a variety of specialists: — information architects who plan the structure and format of information products; — usability specialists and business analysts who identify the tasks that the intended users can perform with the software; — developers and editors of the written content of information for users; — graphic designers with expertise in electronic media; — user interface designers and ergonomics experts working together to design the presentation of the information on the screen. This document is also a reference for those with other roles and interests in the process of developing information for users: — managers of the software development process or the information-development process; — acquirers of information for users prepared by suppliers; — usability testers, reviewers of information for users, subject-matter experts; — developers of tools for creating information for users; — human-factors experts who identify principles for making information for users more accessible and easily used.

This document specifies the purpose and content of all identified systems and software life‐cycle and service management information items (documentation). The information item contents are defined according to generic document types, as presented in Clause 7, and the specific purpose of the document, as presented in Clause 10. This document assumes an organization is performing life‐cycle processes, or delivering system or software engineering services, using either or both of the following: — ISO/IEC/IEEE 12207:2017 software life cycle processes; — ISO/IEC/IEEE 15288:2015 system life cycle processes. ISO/IEC/IEEE 12207:2017 and ISO/IEC/IEEE 15288:2015 define an Information Management process, but do not "detail information items in terms of name, format, explicit content, and recording media" (ISO/IEC/IEEE 12207:2017, 1.4). These standards identify, recommend or require a number of documentation items. This document provides a mapping of processes from the above standards to a set of information items. It provides a consistent approach to meeting the information and documentation requirements of systems and software engineering and engineering service management. The generic document types defined in this document are used to identify the information necessary to support the processes required by ISO/IEC/IEEE 12207:2017 and ISO/IEC/IEEE 15288:2015. The generic document types (which can be referred to as information item types) are used to identify the information necessary to support the processes. For each life‐cycle process or service, it would be possible to prepare a policy, plan, procedures and reports, as well as numerous records, requests, descriptions and specifications. Such an elaboration of the documentation schema would be more rigorous than specified by ISO/IEC/IEEE 12207:2017 or ISO/IEC/IEEE 15288:2015. As ISO/IEC/IEEE 15288:2015, 1.4 points out, "The users of this document are responsible for selecting a life cycle model for the project and mapping the processes, activities, and tasks in this document into that model. The parties are also responsible for selecting and applying appropriate methodologies, methods, models and techniques suitable for the project." Thus, information items are combined or subdivided consistent with the life cycle model, as needed for project or organizational purposes, as further defined in Clause 4 and Clause 5. This document is not a management system standard and does not establish a service management system, quality management system, or asset management system. The scope of this document does not include the following: a) the format or content of recommended input data or input information items, except for the content of those input items that are also output information items; b) instructions on combining or subdividing information items and information item contents of a similar nature; c) guidance on selecting an appropriate presentation format, delivery media and maintenance technology for systems or software life‐cycle data, records, information items or documentation, such as electronic publishing systems, content management systems or data repositories; NOTE ISO/IEC/IEEE 26531 provides requirements for content management and component content management systems. ISO/IEC 26514 provides guidance on formats for user documentation (information for users). d) detailed content for information items related to general business, contractual, organizational and financial management that is not specific to systems and software engineering and engineering service management, such as business strategies, contract change notices (agreement change report), human resources and investment policies, personnel selection criteria, financial budgeting and accounting policies and procedures, cost reports, or payroll data; e) information items showing only approval of an ISO/IEC/IEEE 12207:2017 or ISO/IEC/IEEE 15288:2015 subclause, such as ISO/IEC/IEEE 12207:2017, 6.4.10.3 c) 3

This document supports the interest of information developers and associated roles responsible for producing information for users of software and systems developed within an agile environment. This document takes a process standard approach to specify the way in which information for users can be developed in agile development projects. This document provides requirements of information management and information development processes appropriate for software projects that are using agile development methods. Clause 5 covers the overall requirements for information in agile software development. Clause 6 covers requirements for the information development lead or project manager to plan an agile information development project and manage the information development activities in an agile environment. Clause 7 covers requirements for designing, developing, and providing information for users in an agile environment. Annex A describes agile development practices and methods. This document is intended neither to encourage nor to discourage the use of any particular agile development tools or methods. This document provides guidance on processes appropriate for information developers of information for users in software and systems projects that are using agile development methodologies. It is not limited to the development phase of the life cycle of information for users, but includes activities throughout the whole life cycle. This document is intended for use in all organizations that are using agile development or are considering implementing their projects using these techniques. It is assumed that users of this document have experience or general knowledge of information for users (traditionally called "user documentation") and agile processes.

This document supports the needs of users for consistent, complete, accurate, and usable information. It provides requirements for strategy, planning, managing, staffing, translation, production, and quality and process-maturity assessment for managers of information for users. It specifies processes and procedures for managing information for users throughout the product- or systems-development life cycle. It also includes requirements for key documents produced for managing information for users, including strategic and project plans. This document provides an overview of the information-management processes that are specific for the management of information for users. It addresses the following activities: — developing a comprehensive strategy for information development; — assessing user information needs; — planning and managing an information-development project; — staffing and forming information-development teams; — reviewing and testing information for users; — managing the translation process; — publishing and delivering information for users; — evaluating customer satisfaction and information quality; — measuring productivity, efficiency, and costs; and — evaluating organizational maturity. The guidance in this document applies to multiple project management approaches, including both agile and traditional practices. Traditional practices can encompass predictive, waterfall, or other top-down management methods. Where certain practices are common in agile project management, they are noted. This document is applicable for use by managers of information for users or organizations with information developers. This document can also be consulted by those with other roles and interests in the process of developing information for users: — managers of the product and system development process; — acquirers of information for users prepared by suppliers; — experienced information developers who prepare information for users; — human-factors experts who identify principles for making information for users more accessible and easily used; and — user interface designers and ergonomics experts working together to design the presentation of information. This document can be applied to manage the following types of information for users, although it does not cover all aspects of them: — information for user assistance, training, marketing, and systems documentation for product design and development, based on reuse of user information topics; — multimedia marketing presentations using animation, video, and sound; — information developed for virtual and augmented reality presentations; — computer-based training (CBT) packages and course materials intended primarily for use in formal training programs; and — information describing the internal operation of products.

This document supports the interest of system users in having consistent, complete, accurate, and usable information. It addresses both available approaches to standardization: a) process standards, which specify the way that information products are to be acquired and supplied; and b) information product standards, which specify the characteristics and functional requirements of the information. As defined in ISO/IEC/IEEE 12207 and ISO/IEC/IEEE 15288:2015, the acquisition and supply activities make up the agreement processes of the software or system life cycle. Acquisition and supply of information for users and related services are specializations of those processes. Such services can be acquired and supplied for any part of the information management process, such as the following: - information management; - information design and development; - information editing and review coordination; - information testing, particularly usability testing; - information production and packaging; - information distribution and delivery; - advice on the selection and implementation of information development tools and supporting systems; and - information development process improvement. This document provides an overview of the information management processes that are relevant to the acquisition and supply of information for users. It applies the Agreement processes (acquisition and supply) to information for users, and addresses the preparation of requirements for this information. These requirements are central to the information for users specification and statement of work discussed in this document. This document also addresses requirements for primary document outputs of the acquisition and supply process: the request for proposal and the proposal for documentation products and services. This document is intended for use in acquiring or supplying any type of information for users and is independent of information development or management tools or methodologies. This document might be helpful for acquiring and supplying the following types of information, although it does not cover all aspects of them: - multimedia systems using animation, video, and sound; - computer-based training (CBT) packages and specialized course materials intended primarily for use in formal training programs; - maintenance documentation describing the internal operation of systems software; - collaboratively generated, often known as "wiki", documentation, which will usually need to be curated periodically; and - information for users incorporated into the user interface. This document is applicable to acquirers and suppliers of information for users, including a variety of specialists: - analysts (e.g., business analysts, human factors engineers) who identify the tasks that the intended users will perform with the system; - managers of the software or system development process or the information management process; - managers of the acquisition process, and those who authorize and approve acquisitions; and - managers and authors involved in proposal preparation. It can also be consulted by those with other roles and interests in the information development process: - information designers and architects who plan the structure, format, and content requirements of information products; - experienced authors and editors who develop the written content for information for users; - graphic designers with expertise in electronic media; - user interface designers and ergonomics experts working together to design the presentation of the information on the screen; - usability testers, information development reviewers, technical contacts; - developers of tools for creating on-screen information for users.

ISO/IEC/IEEE 15289:2017 specifies the purpose and content of all identified systems and software life-cycle and service management information items (documentation). The information item contents are defined according to generic document types, as presented in Clause 7, and the specific purpose of the document (Clause 10). ISO/IEC/IEEE 15289:2017 assumes an organization is performing life-cycle processes, or practicing service management, using one or more of the following: - ISO/IEC 12207:2008 (IEEE Std 12207-2008), Systems and software engineering ? Software life cycle processes; - ISO/IEC/IEEE 15288:2015, Systems and software engineering ? System life cycle processes; - ISO/IEC 20000-1:2011 (IEEE Std 20000-1:2013), Information technology ? Service management ? Part 1: Service management system requirements; and - ISO/IEC 20000-2 (IEEE Std 20000-2:2013), Information technology ? Service management ? Part 2: Guidance on the application of service management systems. ISO/IEC/IEEE 15289:2017 provides a mapping of processes from the above standards to a set of information items. It provides a consistent approach to meeting the information and documentation requirements of systems and software engineering and IT service management. ISO/IEC/IEEE 15289:2017 does not establish a service management system.

ISO/IEC/IEEE 15289:2015 provides requirements for identifying and planning the specific information items (information products, documentation) to be developed and revised during systems and software life cycles and service processes. It specifies the purpose and content of all identified systems and software data records and life-cycle information items, as well as records and information items for information technology service management. The information item contents are defined according to generic document types (description, plan, policy, procedure, report, request, and specification) and the specific purpose of the document. For simplicity of reference, each information item is described as if it were published as a separate document. However, information items may be unpublished but available in a repository for reference, divided into separate documents or volumes, or combined with other information items into one document. ISO/IEC/IEEE 15289:2014 is based on the life-cycle processes specified in ISO/IEC 12207:2008 (IEEE Std 12207-2008) and ISO/IEC 15288:2008 (IEEE Std 15288-2008), and the service management processes specified in ISO/IEC 20000-1:2011 (IEEE Std 20000-1:2013) and ISO/IEC 20000-2:2012 (IEEE Std 20000-2:2013).

ISO/IEC 26515:2011 specifies the way in which user documentation can be developed in agile development projects. It is intended for use in all organizations that are using agile development, or are considering implementing their projects using these techniques. It applies to people or organizations producing suites of documentation, to those undertaking a single documentation project, and to documentation produced internally, as well as to documentation contracted to outside service organizations. ISO/IEC 26515:2011 addresses the relationship between the user documentation process and the life cycle documentation process in agile development. It describes how the information developer or project manager may plan and manage the user documentation development in an agile environment. It is intended neither to encourage nor to discourage the use of any particular agile development tools or methods.

ISO/IEC 26511:2011 specifies procedures for managing user documentation throughout the software life cycle. It applies to people or organizations producing suites of documentation, to those undertaking a single documentation project, and to documentation produced internally, as well as to documentation contracted to outside service organizations. It provides an overview of the software documentation and information management processes, and also presents aspects of portfolio planning and content management that user documentation managers apply. It covers management activities in starting a project, including setting up procedures and specifications, establishing infrastructure, and building a team. It includes examples of roles needed on a user documentation team. It addresses measurements and estimates needed for management control, and the use of supporting processes such as change management, schedule and cost control, resource management, and quality management and process improvement. It includes requirements for key documents produced for user documentation management, including documentation plans and documentation management plans. ISO/IEC 26511:2011 is independent of the software tools that may be used to produce or manage documentation, and applies to both printed documentation and on-screen documentation. Much of its guidance is applicable to user documentation for systems including hardware as well as software.

ISO/IEC/IEEE 15289:2011 provides requirements for identifying and planning the specific information items (information products, documentation) to be developed and revised during systems and software life cycles and service processes. It specifies the purpose and content of all identified systems and software data records and life cycle information items, as well as records and information items for information technology service management. The information item contents are defined according to generic document types (description, plan, policy, procedure, report, request, and specification) and the specific purpose of the document. For simplicity of reference, each information item is described as if it were published as a separate document. However, information items may be unpublished but available in a repository for reference, divided into separate documents or volumes, or combined with other information items into one document. ISO/IEC/IEEE 15289:2011 is based on the life cycle processes specified in ISO/IEC 12207:2008 (IEEE Std 12207-2008) and ISO/IEC 15288:2008 (IEEE Std 15288-2008), and the service management processes specified in ISO/IEC 20000-1:2005 and ISO/IEC 20000-2:2005.

ISO/IEC/IEEE 26512:2011 was developed to assist users of ISO/IEC 15288:2008 or ISO/IEC 12207:2008 to acquire or supply software user documentation as part of the software life cycle processes. It defines the documentation process from the acquirer's standpoint and the supplier's standpoint. ISO/IEC/IEEE 26512:2011 covers the requirements for information items used in the acquisition of user documentation products: the Acquisition Plan, Document Specification, Statement of Work, Request for Proposals, and the proposal. It provides an overview of the software user documentation and information management processes which may require acquisition and supply of software user documentation products and services. It addresses the preparation of requirements for software user documentation. These requirements are central to the user documentation specification and Statement of Work. It includes requirements for primary document outputs of the acquisition and supply process: the Request for Proposal and the Proposal for user documentation products and services. It also discusses the use of a Documentation Management Plan and a Document Plan as they arise in the acquisition and supply processes. ISO/IEC/IEEE 26512:2011 is independent of the software tools that may be used to produce documentation, and applies to both printed documentation and on-screen documentation. Much of its guidance is applicable to user documentation for systems including hardware as well as software.

ISO/IEC 26513:2009 supports the interest of software users in receiving consistent, complete, accurate, and usable documentation. It defines the process in which user documentation products are tested. ISO/IEC 26513:2009 is intended neither to encourage nor discourage the use of either printed or electronic (on-screen) media for documentation, or of any particular documentation testing or management tools or methodologies. ISO/IEC 26513:2009 specifies processes for use in testing and reviewing of user documentation. It is not limited to the test and review phase of the life cycle, but includes activities throughout the Information Management and Documentation Management processes. ISO/IEC 26513:2009 provides the minimum requirements for the testing and reviewing of user documentation, including both printed and on-screen documents used in the work environment by the users of systems software. It applies to printed user manuals, online help, tutorials, and user reference documentation. The order of clauses in ISO/IEC 26513:2009 does not imply that the software user documentation should be tested in this order. In each clause, the requirements are media-independent, as far as possible. The informative checklists found in Annexes A and B may be used at each phase of the documentation process to verify that the appropriate steps have been carried out, and that the finished product has acceptable quality. ISO/IEC 26513:2009 can be helpful for testing and reviewing the following types of documentation: documentation of products other than software, for example, hardware or devices; multimedia systems using animation, video, and sound; computer-based training (CBT) packages and specialized course materials intended primarily for use in formal training programs; documentation produced for installers, computer operators, or system administrators who are not end users; maintenance documentation describing the internal operation of systems software. ISO/IEC 26513:2009 is applicable to testers, reviewers, and other related roles, including a variety of specialists: usability testers, documentation reviewers, and subject-matter experts; information designers and architects who plan the structure and format of products in a documentation set; usability specialists and business analysts who identify the tasks the intended users will perform with the software. It can also be consulted by those with other roles and interests in the documentation process. Managers of the software development process or the documentation process should consider the testing of documentation as part of their planning and management activities. Project managers, in particular, have an important role in planning the testing and reviewing of documentation. Testing of the documentation is likely to highlight any defects or nonconformances in tools that are used to create or display on-screen documentation. Similarly, usability testing of the documentation is likely to highlight defects or nonconformances with the presentation or layout of documentation and associated graphics and other media. As a result, there are a number of roles that should be involved in the testing of documentation because their work affects the content, display or presentation of documentation for the user, for example, developers of tools for creating on-screen documentation, graphic designers producing material displayed as part of the documentation, and human-factors experts who identify principles for making documentation more accessible and easily used, also user interface designers and ergonomics experts working together to design the presentation of the documentation on-screen. In some organizations these roles may have different titles, or an individual may perform more than one of these roles. There are other roles that need to understand the test processes for the documentation, for example authors should understand the test processed for the documentation

ISO/IEC 15289:2006 was developed to assist users of systems and software life cycle processes to manage information items (documents). It is based on the life cycle processes specified in ISO/IEC 15288 or ISO/IEC 12207:1995/AMD 1:2002/AMD 2. Information items are essential to preserving what transpired when using system life cycle processes, and may be identified as deliverable documents. ISO/IEC 15289:2006 identifies the purpose and content of all identified systems and software life cycle information items as required for the various life cycle processes. The information item contents are defined according to generic document types (which may be referred to as information item types) and the specific purpose of the document. ISO/IEC 15289:2006 may be applied to any of the activities and tasks of a project, system or software product, or service life cycle. It is not limited by the size, complexity or criticality of the project. It may be applied to all forms of information items, information item content, and document delivery media. Information items may be combined or subdivided as needed for project or organizational purposes. The nomenclature for information items, document titles and contents is informative.

ISO/IEC TR 9294:2005 offers guidance on the management of software documentation to managers responsible for the production of software or software-based products. This guidance is intended to assist managers in ensuring that effective documentation is produced in their organizations. ISO/IEC TR 9294:2005 addresses the policies, standards, procedures, resources and plans with which managers must concern themselves in order to manage software documentation effectively. The guidance given is intended to be applicable to all types of software, from the simplest program to the most complex software suite or software system. All types of software documentation are covered, relating to all stages of the software life cycle. The principles of software documentation management are the same whatever the size of a project. For small projects, much of the detail given in ISO/IEC TR 9294:2005 may not apply, but the principles remain the same. Managers may tailor the recommendations to their particular needs. The guidance given is from the point of view of software documentation management. Detailed advice is not provided on, for example, the content and layout of software documents.

ISO/IEC 18019:2004 provides guidelines for the design and preparation of user documentation for application software. It describes how to establish what information users need, how to determine the way in which that information should be presented to the users, and how then to prepare the information and make it available. Application software includes consumer software packages, software for office applications, business software and specialist software for use by professionals. ISO/IEC 18019:2004 is for use by people responsible for specifying, designing and preparing user documentation for application software and people who manage these activities, including developers of tools for creating hardcopy documentation, product designers, application developers, project managers, authors, programmers, translators and localization staff. It is intended for use in all types of organizations, whether or not a dedicated documentation department is present. In all cases, it can be used as a basis for local standards and procedures. Readers are assumed to have experience or knowledge of software development or documentation development processes.

Addresses the policies, standards, procedures, resources and plans to produce an effective software. Applicable to all types of software from the simplest program to the most complex software system and to all stages of the software lifecycle. Detailed advice on the content and layout of software documentation is not provided. Annex A contains checklists of the policies, standards, procedures and project planing on the software production.

Describes user documentation and cover information supplied with software packages. Is applicable to software packages sold off-the-shelf to consumers for business, scientific, educational and home use. References: ISO 6592; ISO 7185.