ISO Standards for Software User Documentation

George F. Hayhoe
Mercer University
[email protected]

Abstract - During the past five years, a working group • ISO/IEC/IEEE 26515:2012, Systems and
of the International Organization for Standardization software engineering—Developing user do-
(ISO) and the International Electrotechnical Commis- cumentation in an agile environment [5]
sion (IEC) has produced the first-ever international Although all of these standards are relevant to various
standards for software user documentation. Four of aspects of the user documentation development process,
these standards are directed at various audiences in- the core standard is ISO/IEC/IEEE 26514, and this work-
volved in producing user documentation (documenta- shop will focus on that standard.
tion designers and developers, managers, testers and The first part of ISO/IEC/IEEE 26514
reviewers, and acquirers and suppliers), while the fifth … covers the user documentation process for de-
addresses the unique challenges of producing docu- signers and developers of documentation. It de-
mentation in an agile software development environ- scribes how to establish what information users
ment. These standards have also been adopted by the need, how to determine the way in which that in-
IEEE Standards Association. This workshop will formation should be presented to the users, and
briefly describe the process used to develop the five how to design the information and make it avail-
standards and provide an overview of their content. able. [4, p. 1]
Then it will examine in detail how managers can use The second part of the standard defines the minimum
these standards to ensure the quality of documentation requirements
their organizations produce and advance respect for … for the structure, information content, and
documentation within the larger organization. format of user documentation, including both
printed and on-screen documents used in the
Index Terms – Software user documentation, standards, user work environment by users of systems contain-
assistance. ing software. It applies to printed user manuals,
online help, tutorials, and user reference docu-
INTRODUCTION mentation. [4, p. 1]
Over the past four years, the ISO/IEC working group There are no surprises in the standard. It draws on the
responsible for software user documentation standards has best practices for documentation processes defined by
developed a suite of five standards relevant to practition- Hackos [6], and the requirements for usability testing re-
ers and educators in the field of professional communica- flect the approaches advocated by Hackos and Redish [7]
tion, as well as others in software development organiza- and Barnum [8].
tions. The following standards comprise that suite:
• ISO/IEC/IEEE 26511:2012, Systems and CONFORMING TO THE STANDARDS
software engineering—Requirements for The value of standards obviously results from com-
managers of user documentation [1] pliance with their requirements. In the case of this suite of
• ISO/IEC/IEEE 26512:2011, Systems and standards, compliance is carefully defined but is also flex-
software engineering—Requirements for ac- ible. For example, an organization may claim confor-
quirers and suppliers of user documentation mance to ISO/IEC/IEEE 26514 for
[2] • Its documentation process
• ISO/IEC/IEEE 26513:2009, Systems and • Specific documents it has produced
software engineering—Requirements for tes- • Both its process and its documents
ters and reviewers of user documentation [3] An organization can claim conformance to the other
• [4] ISO/IEC/IEEE 26514:2008, Systems and four standards in the suite by requiring documentation
software engineering—Requirements for de- managers to conform to ISO/IEC/IEEE 26511, and docu-
signers and developers of user documentation mentation testers and reviewers to conform to
[4]

978-1-4577-2126-7/12/$26.00 ©2012 IEEE

ISO/IEC/IEEE 26513; requiring that its suppliers of soft- accompanying documentation will have no choice but to
ware user documentation observe the requirements of implement this suite of standards.
ISO/IEC/IEEE 26512; and conforming to ISO/IEC/IEEE
II. Educators
26515 for agile projects.
Furthermore, conformance to the standards is not de- Just as software development managers should take
fined as simply meeting the requirements. The standards notice of these new standards, educators in our profession
permit an organization to tailor their requirements “so that should likewise be aware of ISO/IEC/IEEE 26514 in par-
only necessary and cost-effective requirements are ap- ticular. For a number of years, we have been aware that
plied …” [4, p. 2]. This tailoring may specify how the writing and editing are essential but not sufficient skills
organization’s processes will be adapted to conform to the for a professional communicator. This new standard vali-
standards’ mandatory requirements, or it may change or dates research on core competencies in our profession
delete non-mandatory recommendations to fit the product. with particular emphasis on the need for individual mem-
If the organization’s processes or particular documents bers of a project team to manage their part of the effort.
or projects do not permit conformance to the standards, Many academic programs have been incorporating the
the organization may still use the compatible parts as topics into their curricula, if they did not already do so, as
guidance. In other words, even when tailored compliance part of their periodic assessment to ensure that their gra-
is not possible, this suite of standards provides tested ad- duates have the knowledge and skills they need to suc-
vice for user documentation processes and products. ceed in the workplace. However, ISO/IEC/IEEE 26514
discusses other aspects of documentation project man-
IMPLEMENTING AND BENEFITTING FROM THE agement that may also need to be considered:
STANDARDS • Configuration management (ensuring that
those working on or using the document al-
Obviously, the best way to implement the standards
ways have the latest version and that changes
would be for an organization to recognize that compliance
are not accidentally written over)
with international standards—especially those promulgat-
ed by ISO, IEC, and IEE, which are so widely acknowl- • Cost estimation (both process and product)
edge by software development organizations—gives it a • Quality management
competitive advantage in the marketplace. However, in Those engaged in teaching both undergraduates and
most cases, software development organizations may not graduate students need to familiarize themselves with
be aware of the existence of this new suite of standards, ISO/IEC/IEEE 26514 to ensure that their curricula align
so it is definitely in the best interest of the user documen- with the best practices it describes. Programs that ignore
tation specialists to bring them to the attention of senior this standard are doing their students a great disservice
management. because they will not be competitive in a market that has
As mentioned earlier, there is nothing new in this suite been contracting in recent years. In most cases, bringing
of ISO/IEC/IEEE standards. However, the fact that these programs in line with the requirements of the new stan-
standards have been adopted by ISO should make a dif- dard will require only minor tweaks, but it is just these
ference to software development managers, educators, kinds of revisions that keep programs competitive and
and human resource professionals, and that difference produce graduates who are prepared for the workplace.
benefits professional communicators, students, and the III. Human resource professionals
contractors and other suppliers with whom organizations
collaborate to produce software user documentation. Because it captures the essential knowledge, tasks, and
skills required to produce high quality software user do-
I. Software development managers cumentation in its 143 pages, ISO/IEC/IEEE 26514
No one believes that simply basing our arguments on should be a valuable reference for human resources per-
an ISO standard instead of on a book or article by a pro- sonnel in any organization that employs professional
fessional communicator is a panacea Still, having the let- communicators who generate such documents.
ters I-S-O in our corner may pay off for us sooner rather All too often, hiring managers are at a loss to specify
than later. The external validation that these standards the requirements for the information development posi-
provide should not be underestimated. tions that they must fill. Even those who are professional
At the same time that the standards offer an incentive communicators may not be able to briefly describe the
to management to adopt industry best practices in user knowledge and skills that new hires must possess and the
document development and design, it may pressure pro- responsibilities they must perform. As a result, job post-
fessional communicators who have not implemented them ings for vacancies in our profession are often little more
to do so. Should the European Union require conformance than lists of software products that professional commu-
with this standard, as it did with the ISO 9000 series of nicators use, despite the fact that operating that software
quality standards, many developers of software and its requires much lower level cognitive skills and abilities
than information developers need. The publication of organization of project, and then carefully monitor the
ISO/IEC 26514 will solve that problem. implementation to ensure consistency.
At the broadest level, managers may merely say, “The The advantage here is that once these processes and
successful candidate will have a minimum of one year’s product features have been internalized in an organization
experience with the processes and document characteris- or among working partner organizations, they can be
tics specified in ISO/IEC/IEEE 26514.” If the position is reused and relied upon as benchmarks that will continue
more specialized or the position description can be longer to generate high quality information products.
and more detailed, the following job ad might appear:
LEAD USER DOCUMENTATION ANALYST: CONCLUSION
Responsible for leading the team that performs
audience and task analyses as specified in Producing high quality software user documentation
has always involved a combination of subjective and ob-
ISO/IEC/IEEE 26514, and for using the results
jective elements. The publication of this new suite of
of those analyses to specify the design of print
standards from ISO/IEC/IEEE is a landmark for our field
and online user documentation.
because it adds a dimension of scientific discipline to that
Similarly, human resource analysts, if they are made
aware of the information in the standard, can use it to process and those products.
write detailed position descriptions, to prepare compensa-
tion analyses, and to assist management in performing REFERENCES
periodic personnel reviews. [1] Systems and software engineering—Requirements for man-
The advantages here are obvious. With ISO/IEC/IEEE agers of user documentation, ISO/IEC/IEEE Standard 26511,
26514, it should be easier for organizations to identify and 2012.
hire the best-qualified candidates, and to enhance the ca-
reers of professional communicators they already employ. [2] Systems and software engineering—Requirements for ac-
quirers and suppliers of user documentation, ISO/IEC/IEEE
IV. Collaborators Standard 26512, 2011.

Many—perhaps most—organizations these days are [3] Systems and software engineering—Requirements for testers
collaborating with others on various tasks, and software and reviewers of user documentation, ISO/IEC/IEEE Standard
user documentation is frequently a part of the project. 26513, 2009.
Whether the partner is a subsidiary in Ljubljana, a joint
venture in Shanghai, or a vendor in Bangalore, it is vital [4] Systems and software engineering—Requirements for de-
that all parties understand how to produce quality docu- signers and developers of user documentation, ISO/IEC/IEEE
Standard 26514, 2008.
mentation and what comprises a quality user guide, help
system, or embedded user assistance. Even if the partner [5] Systems and software engineering—Developing user docu-
is across town or in another city in your own country, you mentation in an agile environment, ISO/IEC/IEEE Standard
may not share common work processes or definitions of 26515, 2012.
quality products.
ISO/IEC/IEEE 26512 and 26514 solve this problem by [6] J. T. Hackos, Managing Your Documentation Projects. New
providing common ground. By specifying the standard as York: Wiley, 1994.
the benchmark for a project, your organization can be
assured that all partners involved in the project will know [7] J. T. Hackos and J. C. Redish, User and Task Analysis for
Interface Design. New York: Wiley, 1998.
exactly what is expected of them. The fact that the stan-
dard itself is the product of international collaboration and [8] C. M. Barnum, Usability Testing Essentials: Ready, Set, …
published by the International Organization for Standardi- Test! Burlington, MA: Morgan Kaufman, 2011.
zation gives it credibility and helps ensure its acceptance.
We should not assume, however, that just because the ABOUT THE AUTHOR
standard has been cited as a baseline in a contract or work
agreement, those responsible for the implementation will George Hayhoe is professor of technical communica-
be familiar with the best practices that it describes. De- tion and director of the MS Program in Technical Com-
spite their promulgation in books and articles and at con- munication Management at Mercer University. He is a
ferences for the past two decades and more, many profes- senior member of IEEE and a past president of the IEEE
sional communicators in the U.S. and western Europe Professional Communication Society. He is also a fellow
have never actually implemented these best practices in of the Society for Technical Communication and was
their documentation projects. Therefore, we will all need editor of its journal, Technical Communication, from
to review the standard’s requirements and recommenda- 1996 to 2008.a nd the core
tions, agree on how they will be tailored for a particular