ISO/IEC 26514:2008
(Main)Systems and software engineering — Requirements for designers and developers of user documentation
Systems and software engineering — Requirements for designers and developers of user documentation
ISO/IEC 26514:2008 provides requirements for the design and development of software user documentation as part of the life cycle processes. It defines the documentation process from the viewpoint of the documentation developer. ISO/IEC 26514:2008 also covers the documentation product. It specifies the structure, content, and format for user documentation, and also provides informative guidance for user documentation style. It 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 ISO/IEC 26514:2008 is also applicable to user documentation for systems including hardware.
Ingénierie du logiciel et des systèmes — Exigences pour les concepteurs et les développeurs de la documentation de l'utilisateur
General Information
Relations
Standards Content (Sample)
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 26514:2008(E)
©
ISO/IEC 2008
---------------------- Page: 1 ----------------------
ISO/IEC 26514:2008(E)
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.
COPYRIGHT PROTECTED DOCUMENT
© 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
---------------------- Page: 2 ----------------------
ISO/IEC 26514:2008(E)
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
---------------------- Page: 3 ----------------------
ISO/IEC 26514:2008(E)
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
---------------------- Page: 4 ----------------------
ISO/IEC 26514:2008(E)
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
---------------------- Page: 5 ----------------------
ISO/IEC 26514:2008(E)
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 .
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.