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 1999
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
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
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
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
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
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
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
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
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.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
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 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
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
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 audience definition (see 8.1.3.2).
d) Reasons why the documentation would be used by the intended audience, and for what purpose.
e) Draft tables of contents for the documentation, with estimated page counts, and equivalent detail for other media.
f) The deliverables: number of printed copies, whether electronic copies are to be provided, disk and file formats
(including software versions), and where they will be delivered.
g) Ownership of copyright, and any other proprietary rights.
NOTE The issue of proprietary rights is complex. All contracts for documentation should include references to the ownership of
rights. This may involve assignment of the future copyright in the documentation from the documenter to the acquirer. The
assignment of copyright is then effective when and as the documentation is produced.
h) Provision for translation into other languages.
NOTE Guidance: See annex E for further information.
i) Where appropriate, the level of security or confidentiality of each document.
j) The procedures and controls that will govern the documentation development process, including storage, retrieval,
backup, disposal and quality assurance if required.
k) The production methods, tools and tool versions to be used.
l) The structure of the team in which the documentation development staff will work; optionally, a team selection
plan.
© ISO/IEC 1999 – All rights reserved
NOTE People involved in different phases of the writing and production of documentation need different skills. It may be that a
writer requires a good knowledge of the system being documented, plus experience in writing documentation; an editor may require
only editing experience and no systems knowledge; a layout artist may require no knowledge other than of the layout tools in use.
m) Project dependencies.
n) Person hours required, and costs (see annex F for guidelines on estimating).
o) Project resource requirements, including the information and other resources that the acquirer will provide, and
when.
p) A method for passing information on software changes to the documenter during software development.
q) Plans for the change control and maintenance of the documentation (optional).
r) Plans for post-implementation review (optional).
s) A schedule showing appropriate milestones, including where appropriate:
1) documentation plan approval;
2) preparation, review and correction of each draft;
3) usability testing;
4) camera-ready artwork preparation;
5) printing, binding and distribution.
Where appropriate, each of these elements shall be repeated for each item of documentation.
NOTE 1 It may also be useful to include in the documentation plan samples of similar documentation produced by the documenter,
or even samples of documentation produced by others, to indicate the intended style or layout, or both.
NOTE 2 A documentation plan should be prepared and approved before the development of the documentation begins, to ensure
that all parties agree on the objectives and methods to be used. After approval, the plan should be distributed as widely as
possible; this distribution should include all documentation development staff, and may include acquirer staff and subcontractors
(e.g. printers, typesetters, translators).
8.1.3.2 Audience definition
The documentation plan shall include a definition of the intended audience(s), defining the users in those
audiences in terms of education level, abilities, training, experience and any other characteristics relevant to the
content, structure and use of the documentation.
There are frequently a number of different groups of users, each with different characteristics, and each with a
different purpose in using the documentation. Each type of user, including their characteristics and the tasks they
are trying to perform with help from the documentation, shall be defined separately.
NOTE 1 Data for the audience definition can be obtained from:
a) audience research conducted by the acquirer or documenter;
b) definition supplied by the acquirer;
c) audience definition from another source.
NOTE 2 Wherever possible, documentation development staff should try to meet typical users in their work environments, and
observe them at work.
© ISO/IEC 1999 – All rights reserved
8.1.3.3 Control of documentation plan
After formal agreement, the documenter shall be responsible for the control and distribution of the documentation
plan. A list shall be kept by the documenter of the distribution of accountable copies.
If subsequent changes are made to the documentation plan (and agreed to by the documenter and acquirer), the
documenter shall ensure that all holders of accountable copies are notified of the change.
NOTE Because of the problems that may arise from the existence of outdated copies of the plan, the documenter should prohibit
the uncontrolled copying of the plan, and institute procedures for auditing that all copies of the plan have been updated.
8.1.4 Review
8.1.4.1 General
Review shall be carried out by the acquirer, including discussions with the documenter as necessary.
NOTE The purpose of review is to ensure that submitted material is complete and correct, and that it meets the needs of the
acquirer as defined in the contract and documentation plan.
Reviews should be performed by suitably qualified acquirer personnel, who shall be given the authority to request
changes and to approve the content of the documentation.
NOTE The acquirer should limit the number of reviewers to those necessary for the review function.
The acquirer shall ensure that the safety and legal aspects of the documentation are correct before approving each
draft of the documentation.
Documentation submitted for review shall include a covering letter from the documenter stating the purpose of the
review and the responsibilities of the reviewer.
NOTE 1 The quality of the documentation and the success of reviews will be enhanced by maintaining good communication
between acquirer and documenter throughout the development. This should include informal discussions and the provision of
sample or preliminary material to the acquirer as early as is feasible.
NOTE 2 Where the changes requested are outside the scope of the contract and documentation plan, a contract change may be
necessary.
NOTE 3 Note that the review process does not absolve the documenters from their responsibility of trying to ensure that the
documentation is as accurate and complete as possible.
NOTE 4 Immediately prior to issuing a publication for approval, all screen dumps should be regenerated to ensure that these
illustrations are current. This may be achieved by using the software after the code is frozen, and producing a dump of all screen
representations contained in the publication.
NOTE 5 Acquirer comments resulting from a review should be in the form of either a mark-up of a draft, or written comments with
appropriate references. The acquirer should keep a copy of the changes for comparison with the next draft. The comments should
be such that the documentation development staff can implement the requested changes without further explanation by the
reviewer.
NOTE 6 In large, complex systems, or systems under development while documentation is being written, it may be necessary to
have more than two drafts and a proof. In these cases, the maximum number of drafts should be agreed between the acquirer and
the documenter, and set out in the documentation plan.
NOTE 7 Revision marking (by the use of revision bars, colours, typeface changes or other methods) is an aid to efficient and
effective inspection of drafts. The purpose of revision marking is to highlight those parts of the publication that require inspection.
This avoids situations where multiple draft reviews are required, and reviewers repeatedly re-visit parts of the publication for no
purpose. The use of document comparison tools for the generation of revision marking is strongly recommended, where such tools
are available.
Guidelines for the use of revision marking are as follows:
a) No revision marking should be printed in the first draft of a new publication.
b) Revision marks should be used to show the changes from the original in a revised publication.
© ISO/IEC 1999 – All rights reserved
c) In the second draft, revision marks with a number ‘1’ should be used to indicate places where changes occurred as a result of
first draft review.
d) In a third draft, a number ‘2’ should be used to indicate changes.
e) After the third draft is accepted, all revision marking should be removed before the publication is submitted for proof review.
8.1.4.2 Documentation plan review
The purpose of this review shall be to ensure that the documentation defined by the documentation plan will, when
completed, satisfy the documentation objectives of the acquirer. In approving the documentation plan, the acquirer
is approving all characteristics of the deliverables defined in the plan.
NOTE Acquirers should pay particular attention to the structure, completeness, and usability of the documentation as set out in
the draft table of contents. Where practicable, the documentation plan should be reviewed and approved prior to the start of work
on the first draft. See annex G for guidance on the assessment of a documentation plan.
8.1.4.3 First draft review
The first draft shall contain the body of the documentation as described in the documentation plan, plus table(s) of
contents, appendices and glossary. Where automated indexing tools are used, the index generated shall contain
location references. The spelling, punctuation, style and layout shall be as described in the documentation plan.
The first draft of the documentation shall be reviewed by the acquirer. The purpose of this review is to check the
technical accuracy and completeness of the documentation, to ensure that the draft meets the objectives of the
documentation plan. The spelling, punctuation, style, and layout shall be as defined in the documentation plan.
In approving the first draft, the acquirer approves the technical accuracy, structure, clarity, and completeness of the
documentation except for the changes requested.
NOTE 1 The first draft should be edited before delivery. There are two reasons for this:
a) it ensures that the reviewer is not distracted by having to correct typographic and layout errors;
b) it ensures that any technical inaccuracies caused by the editing process are caught by the reviewer.
NOTE 2 The draft should be reviewed against the objectives, audience definition, table of contents, and other characteristics
approved in the documentation plan. Before returning the first draft with comments, the acquirer should be sure that the draft,
including all corrections, will meet the documentation plan.
8.1.4.4 Second draft review
The second draft shall include all of the changes agreed with the acquirer in the review of the first draft, and shall
contain the content of the deliverables defined in the documentation plan in as near final form as possible.
The purpose of this review is to check that the comments on the first draft have been correctly implemented.
In approving the second draft the acquirer approves all aspects of the documentation except that the physical form
of the draft may not be exactly the same as that of the deliverables.
NOTE Before approving the second draft, the acquirer should be sure that the draft (with the inclusion of the acquirer's
comments on the draft) is ready for proof preparation.
8.1.4.5 Proof review
The proof shall include all of the changes agreed to with the acquirer in the review of the second draft.
The purpose of this review is to check that the comments on the second draft have been correctly implemented.
Any incorrectly implemented comments shall be promptly communicated to the documenter, who shall modify the
documentation accordingly and return copies of the altered sections to the acquirer for further review.
By approving the proof, the acquirer accepts that the document is ready for production.
© ISO/IEC 1999 – All rights reserved
8.1.5 Usability testing of documentation
8.1.5.1 General
The documentation plan shall set out the level of usability testing required.
At a minimum, there should be one usability test of the documentation using the release version of the software.
NOTE 1 Usability testing should be viewed as a complement to inspection and review. Testing during the development cycle
should use a prototype to allow as complete a simulation as possible of the final version.
NOTE 2 When specifying the terms of the testing the usability standard to be measured should be fully defined. This includes
specifying the measurement technique and recording process.
NOTE 3 Where appropriate, the documentation plan should specify a test environment that fully replicates the end user's operating
area. The use of a usability laboratory should be considered. The acquirer may be responsible for the provision of the test
environment.
NOTE 4 Usability testing can be used to measure usability as defined by ISO/IEC 12119:1994, Information technology - Software
packages - Quality requirements and testing.
8.1.5.2 Planning
The terms of the usability testing shall be fully described in the documentation plan, including:
a) point(s) in the development cycle where testing will take place;
b) objectives of the test;
c) measures to be used (e.g. task response times);
d) test environment;
e) number and type of users to participate;
f) process for the recording of test results and recommendations;
g) process for ensuring that test recommendations are implemented;
h) process for communicating test results to all relevant documentation development staff, and to acquirer;
i) responsibilities of documentation development staff representatives present during testing;
j) process for determining the need for further testing.
NOTE 1 To perform usability testing of the documentation, the publications need to be tested with the software they describe. For
effective usability testing, the testing needs to take place as soon as possible so that, if necessary, changes can be made to both
the software and the documentation.
NOTE 2 In scheduling the testing, consideration should be given to the scheduled availability of stand-alone parts of the software,
and the type of function they will provide.
8.1.5.3 Software
Where testing is scheduled to take place before software development is complete, provision shall be made for the
use of a working model, or prototype, of the software. Testing which takes place after software development is
complete shall use the release version of the software.
© ISO/IEC 1999 – All ri
...