ISO/IEC 26514:2008

INTERNATIONAL ISO/IEC
STANDARD 26514
First edition
2008-06-15
Systems and software engineering —
Requirements for designers and
developers of user documentation
Ingénierie du logiciel et des systèmes — Exigences pour les
concepteurs et les développeurs de la documentation de l'utilisateur

Reference number
©
ISO/IEC 2008
PDF disclaimer
This PDF file may contain embedded typefaces. In accordance with Adobe's licensing policy, this file may be printed or viewed but
shall not be edited unless the typefaces which are embedded are licensed to and installed on the computer performing the editing. In
downloading this file, parties accept therein the responsibility of not infringing Adobe's licensing policy. The ISO Central Secretariat
accepts no liability in this area.
Adobe is a trademark of Adobe Systems Incorporated.
Details of the software products used to create this PDF file can be found in the General Info relative to the file; the PDF-creation
parameters were optimized for printing. Every care has been taken to ensure that the file is suitable for use by ISO member bodies. In
the unlikely event that a problem relating to it is found, please inform the Central Secretariat at the address given below.

©  ISO/IEC 2008
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized in any form or by any means,
electronic or mechanical, including photocopying and microfilm, without permission in writing from either ISO at the address below or
ISO's member body in the country of the requester.
ISO copyright office
Case postale 56 • CH-1211 Geneva 20
Tel. + 41 22 749 01 11
Fax + 41 22 749 09 47
E-mail copyright@iso.org
Web www.iso.org
Published in Switzerland
ii © ISO/IEC 2008 – All rights reserved

Contents Page
Foreword. viii
Introduction . ix
1 Scope . 1
2 Conformance. 3
2.1 Application of conformance . 3
2.2 Conformance situations. 3
3 Normative references . 4
4 Terms and definitions. 4
5 User documentation process within the systems/software life cycle. 10
6 Project requirements, objectives, and constraints . 13
6.1 Project objectives . 13
6.2 User documentation requirements and constraints . 14
6.3 Project goals and constraints . 15
6.3.1 Project infrastructure and tools . 16
6.3.2 Schedule constraints. 16
6.4 Users and usability objectives . 17
6.5 Interviewing technical contacts and other experts. 19
6.6 Project planning. 19
6.6.1 Quality management. 20
6.6.2 Version control and change control . 21
6.6.3 Availability of resources . 21
6.6.4 Schedules . 22
6.6.5 Cost estimating . 23
6.6.6 Planning for localization and customization . 24
6.7 Documentation proposal . 24
7 Analysis and design . 25
7.1 Audience and task analysis. 25
7.1.1 Audience analysis. 25
7.1.2 Audience profiles. 27
7.1.3 Task analysis. 28
7.2 User documentation design . 30
7.2.1 Designing for use of content . 31
7.2.2 Designing formats . 31
8 Development and review. 32
8.1 Prototypes and drafts. 32
8.1.1 CM during development. 33
8.1.2 Development of translated and localized documentation. 33
8.2 Evaluation of documentation . 34
8.2.1 Other roles in evaluation of documentation quality. 35
8.2.2 Documentation review procedures. 36
8.3 Documentation testing. 38
8.3.1 Types of documentation tests. 38
8.3.2 Usability tests. 39
9 Production . 40
9.1 Final assembly and review . 40
9.2 Approval . 40
9.3 CM. 41
© ISO/IEC 2008 – All rights reserved iii

9.4 Updating and maintenance . 41
10 Structure of documentation. 41
10.1 Overall structure of documentation . 42
10.1.1 Structure of instructional mode documentation. 43
10.1.2 Structure of reference mode documentation. 43
10.2 Structure of documentation according to audience needs . 43
10.3 Size of topics in onscreen documentation. 45
10.4 User documentation components. 46
10.5 Placement of user documentation components. 47
10.5.1 Initial components . 47
10.5.2 Placement of critical information . 47
11 Information content of user documentation . 47
11.1 Completeness of information . 48
11.2 Accuracy of information. 48
11.3 Content of identification data . 48
11.4 Information for use of the documentation.49
11.5 Concept of operations . 50
11.6 Information for general use of the software.51
11.7 Information for procedures and tutorials . 52
11.7.1 Preliminary information for procedures . 52
11.7.2 Procedural steps . 52
11.7.3 Completion information for procedures .53
11.7.4 Tutorials . 54
11.8 Information on software commands . 54
11.9 Explanations of data entry fields. 55
11.10 Content of error messages and problem resolution . 55
11.11 Content of warnings and cautions . 56
11.12 Information on terminology . 57
11.13 Information on related information sources . 57
11.14 User-supplied content . 58
12 Presentation format of documentation. 59
12.1 General . 59
12.2 Use of printed or on-screen formats. 60
12.3 Selection of appropriate media and format. 61
12.3.1 Comparison of media . 61
12.3.2 Relationship of information displays to the application's displays . 63
12.4 Context-sensitive information . 63
12.5 Accessible documentation. 64
12.5.1 Provide understandable documentation . 64
12.5.2 Provide user documentation in accessible electronic form. 65
12.5.3 Provide text alternatives in on-screen documentation . 65
12.5.4 Write instructions without unnecessary device references . 65
12.5.5 Provide documentation on accessibility features . 65
12.6 Consistency of formats . 65
12.7 Consistency of terminology. 66
12.8 Layout of screens and pages. 67
12.8.1 Grids . 67
12.8.2 Non-scrolling areas. 68
12.8.3 Arrangement of windows . 68
12.8.4 Formats for information area (text) . 69
12.8.5 Formats for headings . 69
12.8.6 Blank space and borders . 69
12.8.7 Vertical spacing. 70
12.9 Legibility. 70
12.9.1 Typefaces and text size . 71
12.9.2 Highlighting text. 71
12.9.3 Lines of text . 72
12.10 Formats for lists . 72
iv © ISO/IEC 2008 – All rights reserved

12.11 Formats for representing user interface elements. 73
12.11.1 Representing control and command input . 73
12.11.2 Representing special keyboard keys. 73
12.12 Use of color . 74
12.13 Navigational features. 75
12.13.1 Using formats to indicate position within a topic . 75
12.13.2 Finding the same information again. 76
12.13.3 Viewing topics in sequence. 76
12.13.4 Formats for active areas . 76
12.13.5 Linking information . 77
12.14 Documentation formats for finding information. 77
12.14.1 Table of contents . 77
12.14.2 Menus. 78
12.14.3 List of illustrations. 79
12.14.4 Index. 79
12.14.5 Search capability . 80
12.15 Formats for warnings, cautions, and notes . 80
12.16 Format for instructions . 81
12.17 Formats for user-supplied annotations. 81
12.18 Formats for illustrations . 81
12.18.1 When to use an illustration. 81
12.18.2 Level of detail in illustrations . 82
12.18.3 Identification of illustrations. 82
12.18.4 Consistent presentation of illustrations. 82
12.18.5 Placement of illustrations . 83
12.18.6 Illustrations of screen displays . 83
12.18.7 Illustrations of printed output. 84
12.18.8 Tables. 85
12.19 Icons and signposts . 85
12.19.1 When to use icons and signposts. 85
12.19.2 Design of icons and signposts. 85
12.19.3 Displaying the names of icons . 86
12.20 Documentation packaging. 87
Annex A (informative) User documentation style guide content . 88
A.1 Writing style . 88
A.2 Language . 88
A.3 Spelling . 88
A.4 Grammar and usage . 88
Annex B (informative) Writing style and techniques for user documentation. 89
B.1 General. 89
B.2 Style for sentences. 90
B.3 Style for paragraphs. 94
B.4 Style for quick-reference information. 95
B.5 Style for installation instructions. 95
B.6 Style for tutorials and task instructions. 96
B.7 Style for describing user interface elements. 96
B.8 Style for descriptions and explanations. 96
B.9 Style for on-screen information . 97
B.10 Style for lists . 97
Annex C (informative) User documentation style for translation and localization. 98
C.1 General. 98
C.2 Terminology . 98
C.3 Style for translation . 99
C.4 Cultural factors . 100
Annex D (informative) Design, development, and production of printed information. 102
D.1 Introduction . 102
D.2 Design . 102
D.3 Production phase. 110
© ISO/IEC 2008 – All rights reserved v

Annex E (informative) Checklists for user documentation . 114
E.1 Checklist for printed manuals. 114
E.2 Checklist for online help . 117
Annex F (informative) Requirements clauses and checklist for the documentation process . 121
Annex G (informative) Requirements clauses and checklist for documentation products. 127
Bibliography . 141

List of Figures
Figure 1 — Sample process of defining the usability goals for an electronic mail system .18
Figure 2 — Sample contents list for a documentation proposal .25
Figure 3 — Sample list of audiences for part of an order fulfillment system.26
Figure 4 — Sample of an audience hierarchy.26
Figure 5 — Sample audience profile.28
Figure 6 — Sample task list for an electronic mail system .28
Figure 7 — Sample task hierarchy.29
Figure 8 — Using audience information needs to determine document content.44
Figure 9 — Using information type and usage to determine delivery method.45
Figure 10 — Sample presentation of an example.50
Figure 11 — Sample overview for a software product module .51
Figure 12 — Sample function description for a spreadsheet function .55
Figure 13 — Sample definition of a term .57
Figure 14 — Sample links to related information .58
Figure 15 — Sample grid for a help system navigator and a topic window.68
Figure 16 — Example of a contents list .78
Figure 17 — Sample text menu .79
Figure 18 — Use of two scales for screen displays.84
Figure D.1 — Example of an A5 page grid .107
Figure D.2 — Example of an A5 page .108
List of Tables
Table 1 — Audience mapping matrix.30
Table 2 — Components of documentation .46
vi © ISO/IEC 2008 – All rights reserved

Table 3 — Example of procedures with the elements marked. 53
Table 4 — Sample Information Profile for one task and one audience . 61
Table 5 — Advantages and disadvantages of various media . 62
Table 6 — Examples of access methods . 64
Table B.1 — Example of conditions presented as a table. 91
Table D.1 — Methods of producing multiple copies . 103

© ISO/IEC 2008 – All rights reserved vii

Foreword
ISO (the International Organization for Standardization) and IEC (the International Electrotechnical
Commission) form the specialized system for worldwide standardization. National bodies that are members of
ISO or IEC participate in the development of International Standards through technical committees
established by the respective organization to deal with particular fields of technical activity. ISO and IEC
technical committees collaborate in fields of mutual interest. Other international organizations, governmental
and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information
technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.
The main task of the joint technical committee is to prepare International Standards. Draft International
Standards adopted by the joint technical committee are circulated to national bodies for voting. Publication as
an International Standard requires approval by at least 75 % of the national bodies casting a vote.
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent
rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.
ISO/IEC 26514 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,
Subcommittee SC 7, Software and systems engineering.

viii © ISO/IEC 2008 – All rights reserved

Introduction
Anyone who uses application software needs accurate information about how the software will help the user
accomplish a task. The documentation may be the first tangible item that the user sees and therefore
influences the user’s first impressions of the software product. If the information is supplied in a convenient
form and is easy to find and understand, the user can quickly become proficient at using the product. Hence,
well-designed documentation not only assists the user and helps to reduce the cost of training and support,
but also enhances the reputation of the product, its producer, and its suppliers.
Although software developers aim to design user interfaces that behave so intuitively that very little separate
documentation is needed, this is rarely possible. Today’s software offers increasingly robust functionality, not
only within applications, but also across applications that intelligently exchange information with one another.
Further, most software designs include underlying rules and calculations, or algorithms, that affect the results
a user can obtain when using the software. Such underlying programming mechanics are discernable by
users, but only through laborious testing. For these reasons and more, user documentation remains an
essential component of usable software products.
Documentation is often regarded as something done after the software has been implemented. However, for
high-quality software documentation, its development should be regarded as an integral part of the software
life cycle process. If done properly, documentation or information management is a big enough job to require
process planning in its own right.
This International Standard was developed to assist users of ISO/IEC 15288:2008, Systems and software
engineering — System life cycle processes, or ISO/IEC 12207:2008, Systems and software engineering —
Software life cycle processes, to design and develop documentation as part of the software life cycle
processes. It defines the documentation process from the documentation developer's standpoint.
NOTE Other International Standards in the ISO/IEC 265NN family are in preparation or planned to address the
documentation and information management processes from the viewpoints of managers, assessors and testers, and
acquirers and suppliers.
In addition to defining a standard process, this International Standard also covers the documentation product.
This International Standard specifies the structure, content, and format for documentation, and also provides
informative guidance for user documentation style.
Earlier standards tended to view the results of the documentation process as a single book or multivolume set:
a one-time deliverable. Increasingly, documentation designers recognize that most user documentation is now
produced from managed re-use of previously developed information (single-source documentation), adapted
for new software versions or presentation in various on-screen and printed media. While this International
Standard does not describe how to set up a content management system (CMS), it is applicable for
documentation organizations practicing single-source documentation.
This International Standard 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 user documentation.
This International Standard conforms to ISO/IEC 12207:2008 as an implementation of subclause 7.2.1,
Software Documentation Management Process, for software user documentation. This International Standard
may be used as a conformance or a guidance document for documentation products, projects, and
organizations claiming conformance to ISO/IEC 15288:2008 or to ISO/IEC 12207:2008.
The primary sources for this International Standard are previous standards IEEE Std 1063-2001, IEEE
standard for software user documentation, and ISO/IEC 18019:2004, Software and system engineering —
Guidelines for the design and preparation of user documentation for application software.
© ISO/IEC 2008 – All rights reserved ix

INTERNATIONAL STANDARD ISO/IEC 26514:2008(E)

Systems and software engineering — Requirements for
designers and developers of user documentation
1 Scope
This clause presents the scope, purpose, organization, and candidate uses of this International Standard.
This International Standard supports the interest of software users in consistent, complete, accurate, and
usable documentation. It includes both approaches to standardization: a) process standards, which specify
the way in which documentation products are to be developed; and b) documentation product standards,
which specify the characteristics and functional requirements of the documentation.
The first part of this International Standard covers the user documentation process for designers and
developers of documentation. 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 to prepare the information and make
it available. It is not limited to the design and development phase of the life cycle, but includes activities
throughout the information management and documentation processes.
The second part of this International Standard provides minimum requirements for the structure, information
content, and format of user documentation, including both printed and on-screen documents used in the work
environment by users of systems containing software. It applies to printed user manuals, online help, tutorials,
and user reference documentation.
This International Standard neither encourages nor discourages the use of either printed or electronic (on-
screen) media for documentation, or of particular documentation development or management tools or
methodologies.
This International Standard may be helpful for developing the following types of documentation, although it
does not cover all aspects of them:
• documentation 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;
• documentation produced for installers, computer operators, or system administrators who are not end
users;
• maintenance documentation describing the internal operation of systems software;
• documentation incorporated into the user interface itself.
© ISO/IEC 2008 – All rights reserved 1

This International Standard is applicable to documentation designers and developers, including a variety of
specialists:
• information designers and architects who plan the structure and format of documentation products in a
documentation set;
• usability specialists and business analysts who identify the tasks that the intended users will perform with
the software;
• those who develop and edit the written content for user documentation;
• graphic designers with expertise in electronic media;
• user interface designers and ergonomics experts working together to design the presentation of the
documentation on the screen.
This International Standard may also be consulted by those with other roles and interests in the
documentation process:
• managers of the software development process or the documentation process;
• acquirers of documentation prepared by suppliers;
• usability testers, documentation reviewers, subject-matter experts;
• developers of tools for creating on-screen documentation;
• human-factors experts who identify principles for making documentation more accessible and easily used.
This International Standard is intended for use in all types of organizations, whether or not a dedicated
documentation department is present, and may 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.
Users of this International Standard should adopt a style manual for use within their own organizations to
complement the guidance provided in the annexes to this International Standard, or adopt an industry-
recognized style guide. Annex A provides guidance for the content of a style guide, and Annexes B and C
provide guidance on style.
The order of clauses in this International Standard does not imply that the documentation should be
developed in this order or presented to the user in this order.
In each clause, the requirements are media-independent, as far as possible. Requirements specific to either
print or electronic media are identified as such, particularly in Clause 12. Annex D provides guidance for the
design of printed documentation.
The checklists in Annex E may be used at each phase of the documentation process to check that the
appropriate steps have been carried out and that the finished documentation satisfies quality criteria.
The checklists in Annexes F and G may be used to track conformance with the requirements of this
International Standard for documentation processes and products.
The bibliography lists works that provide guidance on the processes of managing, preparing, and testing user
documentation.
2 © ISO/IEC 2008 – All rights reserved

2 Conformance
This International Standard may be used as a conformance or a guidance document for projects and
organizations claiming conformance to ISO/IEC 15288:2008 or ISO/IEC 12207:2008.
2.1 Application of conformance
Whether the organization or project has tailored the selected software life cycle processes or adopted them in
full, the organization or project may claim conformance to this International Standard for its documentation
process, for the documentation, or for both.
This International Standard is meant to be tailored so that only necessary and cost-effective requirements are
applied to documentation. Tailoring may take the form of specifying approaches to conform to its mandatory
requirements, or altering its non-mandatory recommendations and approaches to reflect the particular
software and documentation product more explicitly. Tailoring decisions made by the acquirer should be
specified in the contract.
Throughout this International Standard, “shall” is used to express a provision that is binding, “should” to
express a recommendation among other possibilities, and “may” to indicate a course of action permissible
within the limits of this International Standard. When using this International Standard as a guide, replace the
term “shall” with “should”. Use of the nomenclature of this International Standard for the parts of user
documentation (that is, chapters, topics, pages, screens, windows) is not required to claim conformance.
NOTE All “shall” statements are listed in Annex F and Annex G.
2.2 Conformance situations
Conformance of user documentation may be interpreted differently for various situations. The relevant
situation shall be identified in the claim of conformance:
1) When conformance is claimed for an organization, the organization shall make public a document
declaring its tailoring of the life cycle process.
NOTE 1 One possible way for an organization to deal with clauses that cite “the documentation plan” is to
specify that they shall be interpreted in the project plans for any particular documentation project.
2) When conformance is
...