ISO/IEC 18019:2004

INTERNATIONAL ISO/IEC
STANDARD 18019
First edition
2004-01-15


Software and system engineering —
Guidelines for the design and preparation
of user documentation for application
software
Ingénierie du logiciel et du système — Lignes directrices pour la
conception et la préparation de la documentation de l'utilisateur de
logiciels d'application




Reference number
ISO/IEC 18019:2004(E)
©
ISO/IEC 2004

---------------------- Page: 1 ----------------------
ISO/IEC 18019:2004(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.


©  ISO/IEC 2004
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 2004 – All rights reserved

---------------------- Page: 2 ----------------------
ISO/IEC 18019:2004(E)
Contents Page
Foreword. vii
Introduction . viii
1 Scope. 1
2 Terms and definitions. 2
3 Overview. 8
3.1 Forms of documentation. 8
3.2 Deciding what form of documentation to use. 9
3.2.1 General. 9
3.2.2 Information that needs to be on the screen . 9
3.2.3 Information that generally needs to be on paper. 9
3.3 Overview of the structure of this International Standard . 10
3.3.1 General. 10
3.3.2 Checklists. 12
4 The objectives phase. 12
4.1 General. 12
4.2 Collect and interpret project requirements and constraints . 12
4.2.1 General. 12
4.2.2 Product objectives. 13
4.2.3 Sales objectives. 14
4.2.4 Scheduling objectives. 14
4.2.5 Usability objectives. 15
4.2.6 Accessibility objectives. 15
4.2.7 Modification requirements. 15
4.2.8 Internationalisation and national cultural requirements. 16
4.2.9 Translation requirements. 16
4.2.10 Packaging requirements. 17
4.2.11 Legal requirements. 17
4.2.12 Security. 18
4.2.13 Standards and conventions. 18
4.2.14 Cost constraints. 19
4.2.15 Documentation delivery and viewing mechanisms. 19
4.2.16 Quality management. 19
4.2.17 Provision of technical information. 19
4.2.18 Approval authorities. 20
4.2.19 Configuration management. 20
4.2.20 Availability of resources. 20
4.3 Documentation Proposal. 21
5 The planning phase . 23
5.1 General. 23
5.2 Documentation plan. 23
5.2.1 General. 23
5.2.2 Standards. 24
5.2.3 Version control and change control . 24
5.2.4 Personnel. 24
5.2.5 Equipment. 25
5.2.6 Responsibilities. 25
5.2.7 Cost estimates. 26
5.2.8 Schedules. 27
5.2.9 Prototypes and drafts. 27
© ISO/IEC 2004 – All rights reserved iii

---------------------- Page: 3 ----------------------
ISO/IEC 18019:2004(E)
5.2.10 System tests.28
5.2.11 Reviews.28
5.2.12 Usability testing.29
5.2.13 Localisation and customisation.29
5.2.14 Approval.29
5.2.15 Maintenance, updating and future developments .30
5.3 Review of detailed documentation plans.30
6 The analysis and design phase .30
6.1 Audiences.31
6.1.1 Audience analysis.31
6.1.2 Learning stages and frequency of use.32
6.1.3 Working environments.32
6.1.4 Audience profiles.33
6.2 Tasks.34
6.2.1 Task analysis.34
6.2.2 Mapping audiences to tasks .35
6.2.3 Task characteristics.36
6.2.4 Task profiles.36
6.3 Information.36
6.3.1 Information needs.36
6.3.2 Context of use.36
6.3.3 Volume/amount of documentation .37
6.3.4 Media.37
6.3.5 Information profile.39
6.4 Usability.39
6.4.1 Define usability goals .39
6.4.2 Record usability goals .41
6.5 Structure of the documentation suite .41
6.5.1 General.41
6.5.2 Decide what information needs to be provided in the documentation.41
6.5.3 Group information needs into documents .41
6.6 Individual document structures.43
6.6.1 Prepare a list of contents .43
6.6.2 Define the document structure .43
6.7 Document writing style.46
6.7.1 General.46
6.7.2 Awareness and appreciation information.46
6.7.3 Installation instructions.46
6.7.4 Tutorials and task instructions.47
6.7.5 Quick reference information .47
6.7.6 Reference information.47
6.7.7 Diagrams.48
6.7.8 Graphs and charts.48
6.7.9 Illustrations of screen displays.48
6.7.10 Illustrations of printed output .49
7 The development and review phase.50
7.1 General.50
7.2 Prepare and issue drafts .50
7.3 Check and review drafts .51
7.3.1 General.51
7.3.2 Reviewing the information .52
7.3.3 Usability tests.53
7.3.4 System tests.54
7.3.5 Validation and field trials.54
7.4 Prepare subsequent drafts.55
7.5 Prepare document masters .55
7.6 Hand over the finished documentation.56
7.7 Localisation and customisation.56
7.8 Archiving.56
iv © ISO/IEC 2004 – All rights reserved

---------------------- Page: 4 ----------------------
ISO/IEC 18019:2004(E)
8 The evaluation and updating phase. 57
8.1 General. 57
8.2 Evaluate the documentation . 57
8.3 Update the documentation. 57
9 Guidelines for the design of documentation.57
9.1 Introduction. 57
9.2 Product copyright and version details . 58
9.3 Overview of the documentation . 59
9.4 Process descriptions. 59
9.5 Task descriptions. 60
9.6 Explanations of fields and options . 61
9.7 Names and uses of user interface options. 62
9.7.1 Names. 62
9.7.2 Uses. 62
9.8 Descriptions of application functions. 62
9.9 Information messages. 64
9.9.1 Format. 64
9.9.2 On-screen messages. 65
9.10 Definitions of terms . 66
9.11 Concepts. 67
9.12 Exploitation information. 67
9.13 Frequently asked questions. 68
9.14 User-supplied content. 68
9.15 Navigation. 69
9.15.1 Introduction. 69
9.15.2 Accessing on-screen information. 70
9.15.3 Finding the right information - linking information in on-screen documentation. 71
9.15.4 Knowing what the current information is . 74
9.15.5 Knowing the current position within a topic. 75
9.15.6 Finding the same information again . 75
9.15.7 Switching between the application and the documentation . 75
9.15.8 Printing information. 76
9.15.9 Moving to a different topic . 76
9.15.10 Obtaining clarification or amplification of current information . 77
9.15.11 Browsing through information . 77
9.15.12 Viewing topics in sequence . 77
9.15.13 Exiting from the on-screen documentation. 77
9.15.14 Finding user-supplied information. 77
9.15.15 Sizes of topics and fragments . 78
9.16 Presentation. 78
9.16.1 Introduction. 78
9.16.2 Windowing. 79
9.16.3 Layout and grids . 80
9.16.4 Colour. 82
9.16.5 Presentation of text. 84
9.17 Icons and signposts. 90
9.17.1 When to use icons and signposts. 90
9.17.2 Design of icons and signposts. 90
9.17.3 Displaying the names of icons . 91
9.18 Presentation of illustrations. 92
Annex A (informative) Process checklists . 93
Annex B (informative) Design checklist . 98
Annex C (informative) Evaluation of documentation. 114
Annex D (informative) Writing style and techniques . 119
Annex E (informative) Design and preparation of printed information. 131
Annex F (informative) Writing style guides — Contents . 144
© ISO/IEC 2004 – All rights reserved v

---------------------- Page: 5 ----------------------
ISO/IEC 18019:2004(E)
Annex G (informative) ISO/IEC 18019 and related standards.145
Bibliography.146



vi © ISO/IEC 2004 – All rights reserved

---------------------- Page: 6 ----------------------
ISO/IEC 18019:2004(E)
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 member 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 shall not be held responsible for identifying any or all such patent rights.
ISO/IEC 18019 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information technology,
Subcommittee SC 7, Software and system engineering.
© ISO/IEC 2004 – All rights reserved vii

---------------------- Page: 7 ----------------------
ISO/IEC 18019:2004(E)
Introduction
Anyone who uses application software needs accurate information about the correct way to use it. If the
information is supplied in a convenient form and is easy to find and understand, the users can quickly become
proficient at using the product. Consequently their view of the product is positive, with the result that their view
of the supplier is positive too. 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 many software products aim to have user interfaces that behave so intuitively that very little separate
documentation is needed, this is rarely possible.
Documentation is an essential component of any product. Documentation design is crucial; the success or
failure of an en
...