tekom - Europe

tekom.eu Technical Communication Important Standards in Technical Communication Software Documentation

Software Documentation

Standards not only for the Software world

Standards not only for the software world: ISO/IEC/IEEE 2651x series

Prof. Sissi Closs, Karlsruhe University of Applied Sciences - Technology and Economics, C-Topic Consulting GmbH

With regard to standardization, the software world has its own history. Unlike, for example, mechanical engineering or medical technology, for a long time there were no special specifications or standards for the documentation of software. This changed when ISO/IEC 26514, the first standard of the ISO/IEC/IEEE 2651x series of standards for software documentation, was published in 2008. The series has been continued over the years. Today, it consists of five standards that are still little or not at all known, even though they have already been described and presented several times.

Links:
•    Reilly, Annette (2016): Standards for software documentation

The standards at a glance

The series of standards for software documentation with its 2651x number range is part of the "Systems and software engineering" standards series. The aim of the series of standards is to support the creation of consistent, complete, accurate, and usable information for users. The series of standards deliberately emphasizes a process-oriented view. Information for users is not just an end product at the end of a software release, but accompanies the entire life cycle of a product.
Each standard in this series addresses a specific aspect of the information development process with its respective roles, tasks and requirements. In general, all 2651x standards focus on information products for software users. The special features of information products for other audiences and purposes such as development, project management and training are not taken into account. An overview of the standards series is shown in the following table.

Table 1 gives an overview of the standards of the ISO/IEC/IEEE 2651x series: 

ISO/IEC/IEEE StandardSubtitlePrimary audience Brief description of contents
26511Requirements for managers of information for users of systems, software, and servicesPersons in managerial positions, managers    Gives an overview of the individual phases of the information development process from the point of view of management with regard to duties, tasks and expected results
26512Requirements for acquirers and suppliers of information for usersPersons purchasing documentation services and suppliersContains guidelines and rules for cooperation between clients and suppliers
26513Requirements for testers and reviewers of information for usersReviewersDescribes the requirements for the testing and usability testing of information products within the framework of quality assurance
26514Requirements for designers and developers of user documentation    Information developers, technical editorsContains both a standardization approach for the information development process and specifications for the information products created within the software life cycle
26515Developing information for users in an agile environmentPeople working in agile environmentsDescribes requirements for creating and managing information in an agile development environment 

Related standards

The series of standards summarizes existing standards for software documentation and relates them to standards for software development.

Table 2 shows related standards on which the standards series is based: 

IEEE 1063-2001Standard for the design and preparation of user documentation
ISO/IEC 18019:2004Software and system engineering – Guidelines for the design and preparation of user documentation for application software
ISO/IEC 12207:2008System and software engineering – Software life cycle processes
ISO/IEC 15288:2008System and software engineering – System life cycle processes

Who should be interested in the standards?

Even if the standards nominally refer to the software world, they deal with topics that also affect information development in other areas. The standards can therefore also be useful when it is not or not only about software or user assistance. 

Knowledge and consideration of the standards are therefore to be recommended to all those who deal with or come into contact with information development in any way. The standards give guidance and argumentation aids to all entrusted with information development, helping them to improve their position within the company. For the company, the standards support cooperation with other companies, help identify improvement potential and form the basis for quality assurance and contracts.

Where can the standards be obtained?

The standards are currently only available in English and are subject to a fee. They can be purchased directly from the standardization organizations ISO, IEC and IEEE. The foreword and introduction to the standards as well as the scope can be found on the website www.iso.org.

Current status of standardization work

All standards are reviewed regularly every 5 years and revised if necessary. The main standard 26514 is currently being revised. All other standards in the series have already been revised.

Revised versions
The new versions of standards 26511, 26512, 26513 and 26515 have been published.

From document to "Information for Users”
In order to gradually reform the approach originally geared towards documents and print editions, the first step is to critically review and adapt the terminology for the entire series of standards. The current revision cycle has focused on the term "documentation". As it is historically largely associated with forms of documents and printed works, the more open term "information for users" was chosen for the new versions of the standards. This is the first step towards considering other types of information for users as documents.

Participating standardization organizations

AbbreviationDescription
IECInternational Electrotechnical Commission
Develops international standards for electrical engineering and electronics technologies.
 
IEEEInstitute of Electrical and Electronics Engineers
Forms committees for the standardization of techniques, hardware and software.
ISOInternational Organization for Standardization
Develops international standards for all sectors except electrical engineering and electronics (IEC) and telecommunications (ITU).

Further development

Fortunately, tekom supports standards work with the advisory board for legislation and standards. The coordination by Dr. Claudia Klumpp, who holds a doctorate in law and business administration, is particularly promising. She represents tekom's interests in numerous national and international standards committees and was involved in the revision of ISO/IEC 82079-1 (Preparation of instructions for use -- Structuring, content and presentation -- Part 1: General principles and detailed requirements) and the ISO/IEC/IEEE 2651x series of standards. In this way, the software standards and ISO/IEC 82079-1 could be gradually adapted and made consistent. Improvements are desirable in several areas where weak points can be identified:

  • In general, the standards are still too strongly oriented towards the book and print model for information products. Topic-based structures, information integrated into the software or product, and digital media are still not sufficiently taken into account. 
  • There are considerable redundancies and inconsistencies between the individual standards and between these and other standards. In particular, the software standards and the central standard ISO/IEC 82079-1 must be coordinated.
  • The terminology is partly outdated and inconsistent.

Where do standards play a role?

In the course of increasing digitization and networking, the ISO/IEC/IEEE 2651x series of standards for software documentation is becoming increasingly important. Control and monitoring of devices, processes and people are increasingly influenced by software and in some cases even completely taken over. Safety for people and things, usability, rationalization and compatibility play an increasingly important role in software information, which in turn requires reliably verifiable quality criteria. Uniform regulations and standards are an essential prerequisite for this. 

Furthermore, the standards of the ISO/IEC/IEEE 2651x series are not only suitable for the software industry. They are valuable regulations for any kind of information development, as their process-oriented orientation and the consideration of agile processes correspond to today's procedures for product and information development. In addition, by specifically addressing the various players in the development process, such as authors, project managers, quality assurance, etc., they also provide a high level of quality with rules that focus on the respective role and fit their tasks.

Standard 26511 addresses persons in management functions who are responsible for information development. It deals with management tasks in all phases of the development process. This includes

  • Needs analysis
  • Conception of a comprehensive content strategy 
  • Composition of suitable teams
  • Definition of machining cycles and plans
  • Management and coordination of quality assurance
  • Management and coordination of translation into different languages
  • Management and coordination of the publication and production of the desired information products
  • Market observation
  • Business analyses
     
Figure 1: Structuring the processes of client and contractor (from standard 26512)
Figure 1: Structuring the processes of client and contractor (from standard 26512)

Standard 26512, published for the first time in 2011, contains requirements and regulations for cooperation between clients and suppliers of software documentation. It is aimed at persons purchasing documentation services and at service providers offering such services. The revised version was published in 2018. Beside the aforementioned terminology change, only the structure of standard 26512 was slightly revised and the bibliography updated.
The standard regards documentation services as important elements in the product life cycle and lays down rules for both inclusion and provision. These rules serve to structure cooperation between aquirers and suppliers of information for users.. Both sides are considered in parallel and considered equally.

The standard also provides guidance on what needs to be considered from the outset on both sides for successful joint projects. The annexes to the standard, one with checklists for the ordering party and the other for the supplier, are very helpful. Both appendices contain useful requirements, the consistent consideration of which provides a good basis for a transparent, problem-free flow of information development projects. It is defined what must be clarified and delivered by the ordering party and how the ordering party must behave. For clients, this standard is a great support, especially if they have no experience with the purchase of documentation services. Thus, the standard declares the necessity for transparently specifying requirements for the user information to be created according to given guidelines. The standard is also a good set of rules for the contracting party. On the one hand, it can refer to what it has to get from the ordering party and, on the other hand, it receives clear specifications as to what it has to achieve and deliver. For example, the requirements for the contracting party mean that it must be able to present its work to the client in a comprehensible manner at all times. And, for both sides, the important requirement applies that changes to the originally agreed-upon conditions must be communicated openly and at an early stage.

It should be emphasized that the standard is not only applicable if the client and contractor are different companies, but also within a company if the client and contractor are different departments within the same company.

What generally applies to the ISO/IEC/IEEE 2651x series of standards applies in particular to the 26512 standard. When it comes to regulating cooperation between the contracting parties for information development projects, it is useful in all areas, not just software.

Further information

Standard 26513, published in 2011, describes the requirements for the quality assurance of information products and is aimed at reviewers and usability testers.
This standard supports those involved in testing and reviewing user information in the context of software and system development. The standard focuses on the need of users to obtain useful, complete, consistent and correct information about software and systems. There is an important focus on the need to test information products with real users during the development cycle.

The revised version was released in 2017. In addition to the change from "documentation" to "information for users" and the extended literature references, the focus of the revision was on evaluation strategies and methods. In addition, there are extended sections on system tests, usability tests, checking the accessibility of user information as well as tests and reviews of translation and localization. The best innovation is the new appendix with guidelines for user-centered tests and reviews. The guidelines recommend action orientation, consideration of real tasks, attention to error detection and correction and efficient access as test criteria for information products according to the minimalist principles. The approx. 70 quality criteria divided according to these principles are a valuable aid for high-quality and comprehensive quality assurance of information products. 

Further information and links:

26514, the original main standard of the series, consists of a series of content clauses and appendices:

  • User documentation process within the system/software life cycle
  • Project requirements, objectives, and constraints
  • Analysis and design
  • Development and review
  • Production
  • Structure of documentation
  • Information content of user documentation
  • Presentation format of documentation
  • Annex A: User documentation style guide content
  • Annex B: Writing style and techniques for user documentation
  • Annex C: User documentation style for translation and localization
  • Annex D: Design, development, and production of printed documentation
  • Annex E: Checklists for user documentation
  • Annex F: Requirements clauses and checklist for the documentation process
  • Annex G: Requirements clauses and checklist for documentation products

The revised version from 2018 emphasizes the importance of the content strategy even more. It plays a central role as it affects the entire organization, products and customers.
Compliance, which is also an important topic for managers in the information development process, is also emphasized even more, as it requires them to work intensively with product development. This aspect is particularly interesting for areas with high regulatory requirements, such as medical technology. 
The Appendices are very helpful, in particular Appendix B with an exemplary project plan for information development and Appendix C with a plan for translation management.

Further information

This standard focuses on aspects of information development in an agile project environment. The standard does not deal with a specific agile method, but focuses on aspects that are generally important in an agile environment. These include

  • User stories to determine relevant information
  • Management tools such as backlogs for the tasks
  • Planning and execution of tasks in small units such as sprints
  • Close cooperation with the development department
  • Organization of information development with the development process

The standard also emphasizes that information development can take on a variety of tasks in an agile team. In addition to the development of "information for users", this includes the execution of tests, the compilation of feedback, participation in the design of the user experience and the training of team members.

Further information and links: