ISO/IEC 15910:1999

INTERNATIONAL ISO/IEC
STANDARD 15910
First edition
1999-12-15
Information technology — Software user
documentation process
Technologies de l'information — Procédé de documentation d'utilisateur de
logiciel
Reference number
ISO/IEC 15910:1999(E)
©
ISO/IEC 1999

---------------------- Page: 1 ----------------------
ISO/IEC 15910:1999(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 1999
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 734 10 79
E-mail copyright@iso.ch
Web www.iso.ch
Printed in Switzerland
© ISO/IEC 1999 – All rights reserved
ii

---------------------- Page: 2 ----------------------
ISO/IEC 15910:1999(E)
Contents Page
1 Scope .1
2 Conformance.1
3 Normative reference .1
4 Terms and definitions.2
5 Quality management.6
6 Tailoring .7
7 Objectives.7
8 Requirements .7
8.1 The documentation process .7
8.1.1 General.7
8.1.2 Provision of source material .7
8.1.3 Documentation plan .9
8.1.4 Review.11
8.1.5 Usability testing of documentation.13
8.1.6 Documentation development subcontracted to other companies.14
8.1.7 Change control and document maintenance.14
8.2 Content of a style specification.15
8.2.1 General.15
8.2.2 Writing style .15
8.2.3 Paper documentation .15
8.2.4 Electronic documentation.20
Annex A (informative) Cross-reference to ISO/IEC 12207.23
Annex B (informative) Calling the International Standard from a contract.24
Annex C (informative) Sample documentation plan: ABC tape management system user documentation.26
Annex D (informative) Relationship between audiences, tasks, paper and on-line documentation.31
Annex E (informative) Writing in English for translation .34
Annex F (informative) Estimating .38
© ISO/IEC 1999 – All rights reserved
iii

---------------------- Page: 3 ----------------------
ISO/IEC 15910:1999(E)
Annex G (informative) Assessing a documentation plan.41
Annex H (informative) Sample style specification .42
Bibliography .47
Index.49
Figures
Figure 1 — Documentation process overview.8
Figure D.1 — Audience hierarchy .31
Figure D.2 — Task hierarchy .32
Figure D.3 — Information needs.32
Figure D.4 — Summary of the process.33
Tables
Table 1 — Subtended angle and point size.22
Table A.1 — Cross-reference to ISO/IEC 12207.23
Table C.1 — Style guide .26
Table C.2 — Project team.28
Table C.3 — Schedule .30
Table F.1 — Estimated times .38
Table H.1 — Style elements and values .42
© ISO/IEC 1999 – All rights reserved
iv

---------------------- Page: 4 ----------------------
ISO/IEC 15910:1999(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.
International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 3.
In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
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 International Standard may be the subject of
patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.
International Standard ISO/IEC 15910 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information
technology,SubcommitteeSC7, Software engineering.
Annexes A to H of this International Standard are for information only.
© ISO/IEC 1999 – All rights reserved
v

---------------------- Page: 5 ----------------------
ISO/IEC 15910:1999(E)
Introduction
There are two major types of standards:
a) product standards, which specify the characteristics and functional requirements of a product;
b) process standards, which specify the way in which products are to be developed.
The ever-increasing application and complexity of computer software makes necessary the availability of complete,
accurate and understandable documentation to those who use the software. This International Standard provides a
tool for achieving this by specifying those activities (what is to be done, and who is to do it) that can affect the
quality of software user documentation.
Documentation is often regarded as something done after the software has been implemented. However, for quality
software documentation production, it should be regarded as an integral part of the software production process. If
done properly, it is a big enough job to require process planning in its own right. The purpose of this International
Standard is to encourage software developers to give this documentation process its due place. This International
Standard also gives users and clients a tool to ensure that this process takes place.
This International Standard's main activity is the creation of a comprehensive plan for developing the
documentation. This is necessary because results are more likely to happen if they are planned. To comply with
this International Standard, the plan must include a style specification. This International Standard does not specify
the content of this style specification (i.e. it does not specify a particular layout or typeface), but it specifies what a
style specification must cover. This International Standard also specifies what kinds of information the acquirer is to
make available to the documenter, and who is to review and reproduce the documentation.
Further information on this topic may be obtained by contacting relevant organizations or from other literature (see
Bibliography).
This International Standard was prepared by ISO/IEC JTC 1 SC 7, based on Australian Standard AS 4258:1994.
For a mapping between ISO/IEC 12207:1995 and this International Standard, see annex A.
© ISO/IEC 1999 – All rights reserved
vi

---------------------- Page: 6 ----------------------
INTERNATIONAL STANDARD ISO/IEC 15910:1999(E)
Information technology — Software user documentation
process
1 Scope
This International Standard specifies the minimum process for creating all forms of user documentation for software
which has a user interface. Such forms of documentation include printed documentation (e.g. user manuals and
quick-reference cards), on-line documentation, help text and on-line documentation systems.
This International Standard conforms with ISO/IEC 12207:1995, Information technology — Software life cycle
processes, as an implementation of the user documentation part of 6.1: Documentation.
If effectively applied, this International Standard will support the development of documentation which meets the
needs of the users.
This International Standard is intended for use by anyone who produces or buys user documentation.
This International Standard is applicable to not only printed documentation, but also help screens, the help delivery
system, and the on-line text and delivery system. See the bibliography.
This International Standard is intended for use in a two-party situation and may be equally applied where the two
parties are from the same organization. The situation may range from an informal agreement up to a legally binding
contract. This International Standard may be used by a single party as self-imposed tasks.
NOTE Annex B provides further guidance on the use of this International Standard in a contract between acquirer and
documenter.
2 Conformance
Conformance with this International Standard is defined as the demonstration that the process set out in clause 8 of
this International Standard has been followed.
3 Normative reference
The following normative document contains provisions which, through reference in this text, constitute provisions of
this International Standard. For dated references, subsequent amendments to, or revisions of, any of these
publications do not apply. However, parties to agreements based on this International Standard are encouraged to
investigate the possibility of applying the most recent edition of the normative document indicated below. For
undated references, the latest edition of the normative document referred to applies. Members of ISO and IEC
maintain registers of currently valid International Standards.
ISO 216:1975, Writing paper and certain classes of printed matter — Trimmed sizes — A and B series.
© ISO/IEC 1999 – All rights reserved
1

---------------------- Page: 7 ----------------------
ISO/IEC 15910:1999(E)
4 Terms and definitions
For the purposes of this International Standard, the following terms and definitions apply.
4.1
A4, A5
International Standard paper sizes, A4 is 210 mm by 297 mm and A5 is 148 mm by 210 mm; see ISO 216:1975
4.2
acquirer
an organization that acquires or procures a system or software product from a supplier
[ISO/IEC 12207:1995, definition 3.1]
NOTE The acquirer could be one of the following: buyer, customer, owner, user, purchaser. In this International Standard the
acquirer is the party who requests the documentation. Note that the acquirer is not necessarily part of the audience for the
documentation. Note also that the acquirer may belong to the same organization as the documenter, or may be the developer of
the software.
4.3
audience
category of users sharing the same or similar characteristics and needs (e.g. purpose in using the documentation,
tasks, education level, abilities, training, experience) that determine the content, structure and use of the intended
documentation
NOTE There may be a number of different audiences for a software product's documentation (e.g. management, data entry,
maintenance).
4.4
audience research
planned process of interview, and of the analysis of interview records and personnel records
NOTE The purpose of audience research is to determine the abilities, training, experience, limitations, prejudices and
preferences of the intended readers of a document.
4.5
B5
International Standard paper size, 176 mm by 250 mm; see ISO 216:1975
4.6
back matter
material that appears at the end of a book or manual, such as an index
4.7
camera-ready originals
set of images on paper, photographic film or another suitable medium from which a printing plate can be made by
direct photographic transfer, and where each image contains all of the necessary text and graphic elements for one
complete page of paper documentation, with each element in the correct position
4.8
cut-off date
date after which changes to the software are reflected in the next, rather than the current, issue of the
documentation
4.9
deliverables
items whose delivery to the customer is a requirement of the contract
© ISO/IEC 1999 – All rights reserved
2

---------------------- Page: 8 ----------------------
ISO/IEC 15910:1999(E)
4.10
document
equivalent to an item of documentation (cf)
4.11
documentation
printed user manuals, on-line documentation and help text which describe how to use a software product
4.12
documentation development staff
all staff involved in any phase of the planning, writing, editing and production of documentation
NOTE This includes authors, designers, illustrators and project management staff.
4.13
documentation plan
document which sets out the essential elements of the documentation project
4.14
documenter
party preparing the documentation
NOTE The term developer (as defined in ISO/IEC 12207:1995, definition 3.8) is not used here, as in the case of documentation
the developer of the software is often the acquirer of the documentation, and the use of the term developer might be confusing in
this context. Consequently the term documenter is used.
4.15
electronic copy
computer disk or other computer-readable medium containing a file or files from which the document can be printed
4.16
en dash
dash the same width as a lower-case ‘n’
4.17
endnotes
notes collected at the end of a chapter or document
4.18
foldout
single page wider than the rest, normally folded so that it does not protrude, that may be unfolded by the reader -
Contrast with Throwclear
4.19
footer
material repeated at the bottom of each page (e.g. page number)
4.20
footnote
text at the bottom of a page, usually in smaller type, which is referenced by means of a number or other device in
the text on the same page
4.21
front matter
material that comes at the front of a book or manual, such as the title page and table of contents
4.22
header
material repeated at the top of each page
© ISO/IEC 1999 – All rights reserved
3

---------------------- Page: 9 ----------------------
ISO/IEC 15910:1999(E)
4.23
heading
text that identifies the topic that will be covered in the following text
4.24
help system
see on-line documentation system
4.25
help text
text which is accessed by the user through the use of software, and which is automatically selected according to
the context in which it is called up; i.e. help text is context-sensitive
4.26
item of documentation
information designed for a specific audience for a specific purpose, and using a specific medium (e.g. book, disk,
quick-reference card, video) of a particular format
4.27
location reference
indicator following a heading or subheading in an index, showing to which part of the document the heading or
subheading refers
4.28
mark-up
document with comments written on it indicating changes that need to be made; also the process of producing such
a document
4.29
mechanicals
printing, binding, production and layout details for paper-based documentation
4.30
navigation
means by which a user moves from one part of a software application to another
4.31
on-line documentation
information accessed by the user through the use of software, but that may not be sensitive to context - See also
Help text
4.32
on-line documentation system or help system
ancillary part of a program, or sometimes a separate program, that allows the user to view parts of the on-line
See also on-line documentation and Help text
documentation or help text on request -
4.33
orphan
line of text on its own at the end of a page
4.34
paper documentation
that part of the documentation which is in printed form
4.35
pixel
smallest element of a screen display; short for ‘picture element’
© ISO/IEC 1999 – All rights reserved
4

---------------------- Page: 10 ----------------------
ISO/IEC 15910:1999(E)
4.36
point
measure of vertical distance; there are approximately 2,8 points to the millimetre (approximately 72 points to the
inch)
4.37
process
a set of interrelated activities, which transform inputs into outputs
[ISO/IEC 12207:1995, definition 3.17]
4.38
product
complete set of computer programs, procedures and associated documentation and data designed for delivery to a
user
NOTE Also referred to as a software product.
4.39
production
steps involved in taking draft text and turning it into camera-ready originals, completed help text or on-line
documentation
4.40
proof
final copy of a paper document presented to the acquirer for review prior to publication
NOTE Unless alterations are requested, the finished document should be identical to the proof copy in all respects other than
paper stock, binding and colours. Proofs are generally photocopies of the camera-ready originals.
4.41
prototype
model or preliminary implementation of a piece of software suitable for the evaluation of system design,
performance or production potential, or for the better understanding of the software requirements
4.42
recto
page on the same side (i.e. right or left) as the front cover
4.43
screen dump
representation of what the user will see while using the software
4.44
system
an integrated composite that consists of one or more of the processes, hardware, software, facilities, and people,
that provide a capability to satisfy a stated need or objective
[ISO/IEC 12207:1995, definition 3.31]
4.45
table of contents
list of the headings in a document in page number order, with page numbers shown against each heading
4.46
table of effective pages
list showing the latest version number of each page in a loose-leaf paper document; where individual pages are
replaced, the table of effective pages shows the old version number for the unaltered pages, and the new version
number for the replaced pages
© ISO/IEC 1999 – All rights reserved
5

---------------------- Page: 11 ----------------------
ISO/IEC 15910:1999(E)
4.47
team selection plan
document specifying the qualifications, experience and training needs of documentation development staff
4.48
throwclear
foldout whose print area is such that all of the material on the page can be viewed with the book shut, so that it can
be viewed at all times while looking at any of the preceding pages of the book
4.49
usability laboratory
typically, a suite of evaluation and observation rooms which may be fitted with video and audio equipment for
recording user responses
4.50
usability testing
formal process for evaluating the suitability of documentation
4.51
user interface
interface that enables information to be passed between a human user and hardware or software components of a
computer system
4.52
user
an individual or organization that uses the operational system to perform a specific function
[ISO/IEC 12207:1995, definition 3.34]
NOTE See also Audience.
4.53
verso
page on the opposite side (i.e. right or left) as the front cover
4.54
white space, active
area around textual or graphical elements, not including margins, which breaks up text, separates topic and sub-
topic groupings, indicates hierarchical and topical relationships, highlights information and makes text easier to
read
4.55
white space, passive
top, bottom, left and right margins which surround text
4.56
widow
line of text on its own at the start of a page
5 Quality management
If the development of the software being documented is subject to a quality management standard, the provisions
of that standard apply equally to the development of software and to its documentation.
NOTE Even where a quality management standard is not referenced in a contract, documenters are encouraged to use a quality
management system that complies with appropriate quality management standards. Regarding quality in general, see also ISO/IEC
12119:1994, Information technology - Software packages - Quality requirements and testing.
© ISO/IEC 1999 – All rights reserved
6

---------------------- Page: 12 ----------------------
ISO/IEC 15910:1999(E)
6 Tailoring
This International Standard is one implementation of the documentation process as defined in ISO/IEC
12207:1995, Information technology — Software life cycle processes, and can be tailored to suit particular projects
(see annex B).
7 Objectives
This International Standard is basically a process standard. It does not mandate any particular document layout,
document content or any other aspect of the completed documentation; rather, it mandates the way in which the
documentation process is to be planned and carried out.
8 Requirements
8.1 The documentation process
8.1.1 General
The activities of the documentation process shall be performed in the sequence shown in Figure 1, which has two
shaded boxes. All of the activities within a shaded box shall be completed before beginning on the activities in the
next shaded box. Within a shaded box, activities may be undertaken in parallel. Broken lines indicate possible
iterations.
In cases where the minimum content of the documentation has been specified by the acquirer (ISO 6592 or
ISO 9127:1988 may for example be used for this purpose), this should be taken into account by the documenter
during development of the documentation plan.
8.1.2 Provision of source material
The acquirer shall provide to the documenter access to:
a) all relevant specifications, record formats, screen and report layouts, CASE tool output, and any other information
necessary for the preparation of the documentation;
b) an operating copy of the software, if available;
c) the analysts and programmers of the software, including the timely and accurate resolution of questions raised by
documentation development staff;
d) where possible, typical users for audience analysis and usability testing.
It shall be the documenter's responsibility to ensure that access to the acquirer's software development staff is kept
to the minimum required to gain an understanding of the product and its audiences.
NOTE The documenter is not responsible for developing, checking or correcting source information, only for communicating it.
Whether or not the documenter is also the developer of the software, the acquirer shall supply copies of all
applicable standards, style and format guidelines, and other related materials (unless generally available). The
documenter shall distribute this material to those documentation development staff who require it.
It shall be the responsibility of the acquirer to ensure that all of the material delivered by the acquirer to the
documenter is complete and correct when delivered, and that it is kept up to date after delivery.
The acquirer warrants that none of the material provided infringes the intellectual property rights of any other party.
© ISO/IEC 1999 – All rights reserved
7

---------------------- Page: 13 ----------------------
ISO/IEC 15910:1999(E)
Obtain source material (Acquirer and
Documenter) - clause 8.1.2
Develop documentation plan
(Documenter) - clause 8.1.3
Review documentation plan (Acquirer) -
clause 8.1.4.2
Develop documentation (Documenter) -
as set out in documentation plan
Review
documentation
(Acquirer) - clause
8.1.4.3 to 8.1.4.5
Usability testing
(Documenter and
Acquirer) - as set out
in documentation plan
(see clause 8.1.5)
Reproduce and distribute (Documenter) -
as set out in documentation plan (see
clause 8.1.3.1 (f))
Figure 1 — Documentation process overview
© ISO/IEC 1999 – All rights reserved
8

---------------------- Page: 14 ----------------------
ISO/IEC 15910:1999(E)
The documenter shall take all reasonable steps to ensure that the material provided by the acquirer is kept in good
order, shall secure the information to the requirements of the acquirer, and shall return all material to the acquirer at
the completion of the documentation project.
NOTE In some cases, not all material needs to be returned; this should be defined in the contract. In some cases, the material
passed by the acquirer to the documenter is required to be kept confidential and secured. The contract should specify the level of
confidentiality or security the acquirer requires from the documenter for material passed to the documenter.
8.1.3 Documentation plan
8.1.3.1 General
The documenter shall prepare a documentation plan which specifies the work to be carried out in creating the
documentation. The documentation plan shall be formally agreed to by the acquirer to signify that it fully covers the
acquirer's requirements.
NOTE The documentation plan will generally cover the whole documentation suite, including, for example, user manuals, on-line
documentation, help text and quick-reference cards. See annex C for a sample plan. See also annex D for a description of the
design process.
The documentation plan shall formally describe the scope and limitations of the planned documentation, as well as
important documentation analysis and design decisions. It shall also specify the processes and controls to be
implemented during documentation development.
The documentation plan shall include (but not be limited to) the following:
a) The working title, purpose, scope and limitations of the planned documentation.
b) A style specification, as set out in 8.2 of this International Standard.
c) An audie
...