ISO/IEC TR 9294:2005
(Main)Information technology — Guidelines for the management of software documentation
Information technology — Guidelines for the management of software documentation
ISO/IEC TR 9294:2005 offers guidance on the management of software documentation to managers responsible for the production of software or software-based products. This guidance is intended to assist managers in ensuring that effective documentation is produced in their organizations. ISO/IEC TR 9294:2005 addresses the policies, standards, procedures, resources and plans with which managers must concern themselves in order to manage software documentation effectively. The guidance given is intended to be applicable to all types of software, from the simplest program to the most complex software suite or software system. All types of software documentation are covered, relating to all stages of the software life cycle. The principles of software documentation management are the same whatever the size of a project. For small projects, much of the detail given in ISO/IEC TR 9294:2005 may not apply, but the principles remain the same. Managers may tailor the recommendations to their particular needs. The guidance given is from the point of view of software documentation management. Detailed advice is not provided on, for example, the content and layout of software documents.
Technologies de l'information — Lignes directrices pour la gestion de la documentation technique du logiciel
General Information
Relations
Standards Content (Sample)
TECHNICAL ISO/IEC
REPORT TR
9294
Second edition
2005-02-01
Information technology — Guidelines for
the management of software
documentation
Technologies de l'information — Lignes directrices pour la gestion de la
documentation technique du logiciel
Reference number
ISO/IEC TR 9294:2005(E)
©
ISO/IEC 2005
---------------------- Page: 1 ----------------------
ISO/IEC TR 9294:2005(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 2005
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 2005 – All rights reserved
---------------------- Page: 2 ----------------------
ISO/IEC TR 9294:2005(E)
Contents
Foreword. iv
Introduction . v
1 Scope. 1
2 Normative references . 1
3 Terms and definitions. 1
4 The managerial role . 2
4.1 Overview . 2
4.2 Evidence of managerial commitment and support . 2
5 The functions of software documentation .2
5.1 Overview . 2
5.2 Communication to management . 3
5.3 Task-to-task communication . 3
5.4 Quality assurance . 3
5.5 Instruction and reference. 3
5.6 Software support. 3
5.7 Historical reference. 3
6 Establishing documentation policies . 3
7 Establishing documentation standards and guidelines . 4
7.1 Overview . 4
7.2 Selecting a software life cycle model . 5
7.3 Defining document type and content. 5
7.3.1 Introduction . 5
7.3.2 Development documentation. 5
7.3.3 Product documentation. 6
7.3.4 Project management documentation. 6
7.4 Defining document quality. 7
7.5 Defining document formats . 7
7.6 Defining a document identification system .8
8 Establishing documentation procedures .8
9 Allocating resources to documentation . 9
9.1 People. 9
9.1.1 Managers . 9
9.1.2 Project Team Members. 9
9.2 Facilities. 9
9.3 Funding . 9
10 Documentation plan. 10
10.1 Overview . 10
10.2 Information in the documentation plan . 10
10.3 Documentation schedule . 10
Annex A (informative) Checklist for software documentation management . 12
A.1 Policies checklist . 12
A.2 Standards checklist . 12
A.3 Procedure checklist. 12
A.4 Project planning checklist . 13
Bibliography . 14
© ISO/IEC 2005 – All rights reserved iii
---------------------- Page: 3 ----------------------
ISO/IEC TR 9294:2005(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 national bodies casting a vote.
In exceptional circumstances, the joint technical committee may propose the publication of a Technical Report
of one of the following types:
— type 1, when the required support cannot be obtained for the publication of an International Standard,
despite repeated efforts;
— type 2, when the subject is still under technical development or where for any other reason there is the
future but not immediate possibility of an agreement on an International Standard;
— type 3, when the joint technical committee has collected data of a different kind from that which is normally
published as an International Standard (“state of the art”, for example).
Technical Reports of types 1 and 2 are subject to review within three years of publication, to decide whether
they can be transformed into International Standards. Technical Reports of type 3 do not necessarily have to
be reviewed until the data they provide are considered to be no longer valid or useful.
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 TR 9294, which is a Technical Report of type 3, was prepared by Joint Technical Committee
ISO/IEC JTC 1, Information technology, Subcommittee SC 7, Software and system engineering.
This second edition cancels and replaces the first edition (ISO/IEC TR 9294:1990), which has been technically
revised. Changes were made to update the document with current methodologies and to align it with
ISO/IEC 12207:1995/Amd.1:2002.
iv © ISO/IEC 2005 – All rights reserved
---------------------- Page: 4 ----------------------
ISO/IEC TR 9294:2005(E)
Introduction
Documentation is needed for all stages of the software life cycle. As a result, the preparation and maintenance
of documentation constitute a necessary and continuous effort from the inception of the software through to its
disposal. Documentation begins with and is consistent with a software life cycle process, such as the initiation
of a software project, and continues with the design, development, testing, installation, use, modification and
enhancement of the software. The documentation process can be regarded as having ended only when the
information about the software is no longer needed and the use of the software is terminated.
Documentation is an essential component for the success of any software project, and the production of
documentation implies the commitment of time, effort and money. It is the responsibility of management to
ensure the effective deployment of these resources that recognizes the importance of documentation to the
quality and success of the software product.
ISO/IEC TR 9294 is one of the guidelines of the Documentation Process in ISO/IEC 12207:1995/Amd1:2002
(from the viewpoint of managing the products of the documentation process). ISO/IEC 15910:1999 and
ISO/IEC FDIS 18019, are guidelines for the user documentation process. These documents are useful in
integrating the processes of documentation and software development. ISO/IEC 6592:2000 is useful in
identifying the document contents.
The guidelines for the Documentation Process of ISO/IEC 12207:1995/Amd1:2002 and this Technical Report
describe a management point of view of software documentation. The relationships between this document
and other related International Standards are shown in Figure 1. This TR is one of the guidelines for the
Documentation Process of ISO/IEC 12207:1995. Clause 6 includes a reference to the User Documentation
Process of ISO/IEC 15910:1999 and ISO/IEC FDIS 18019; and 7.2 has a reference to ISO/IEC CD 15289
showing typical development and product documents.
G uidelines for the U ser
D ocum entation
D ocum entation
M anagem ent of
cover inform ation
P rocess
docum entation
for packaging
IS O /IE C
IS O /IE C
IS O /IE C
9294
18019
9127
O verall
IS O /IE C
15910
C ontractual
IS O /IE C IS O /IE C
IS O /IE C
12207 15289
6592
D escription of
In sta ntiation of th e
D ocum entation
life-cycle
D ocum entatio n P rocess
hierarchy
Inform ation item s
Figure 1 — Relationship of TR 9294 to documentation International Standards
© ISO/IEC 2005 – All rights reserved v
---------------------- Page: 5 ----------------------
TECHNICAL REPORT ISO/IEC TR 9294:2005(E)
Information technology — Guidelines for the management of
software documentation
1 Scope
This Technical Report (TR) offers guidance on the management of software documentation to managers
responsible for the production of software or software-based products. This guidance is intended to assist
managers in ensuring that effective documentation is produced in their organization.
This TR addresses the policies, standards, procedures, resources and plans with which managers must
concern themselves in order to manage software documentation effectively.
The guidance given is intended to be applicable to all types of software, from the simplest program to the most
complex software suite or software system. All types of software documentation are covered, relating to all
stages of the software life cycle.
The principles of software documentation management are the same whatever the size of a project. For small
projects, much of the detail given in this TR may not apply, but the principles remain the same. Managers may
tailor the recommendations to their particular needs.
The guidance given is from the point of view of software documentation management. Detailed advice is not
provided on, for example, the content and layout of software documents.
2 Normative references
The following referenced documents are indispensable for the application of this document. For dated
references, only the edition cited applies. For undated references, the latest edition of the referenced
document (including any amendments) applies.
ISO/IEC 12207:1995/Amd1:2002, Information Technology — Software life cycle processes — Amendment 1
ISO/IEC 18019:2004, Software and system engineering — Guidelines for the design and preparation of user
documentation for application software
3 Terms and definitions
For the purposes of this Technical Report, the following terms and definitions apply.
3.1
document
uniquely identified unit of information for human use, such as a report, specification, manual or book, in
printed or electronic form
© ISO/IEC 2005 – All rights reserved 1
---------------------- Page: 6 ----------------------
ISO/IEC TR 9294:2005(E)
3.2
documentation
collection of related documents that are designed, written, produced and maintained
3.3
software product
set of computer programs, procedures, and possibly associated documentation and data
[ISO/IEC 12207:1995, 3.26]
4 The managerial role
4.1 Overview
Managers commit their organisations to a documentation effort and support that effort by implementing
documentation policies, standards, procedures, resource allocations and plans. Effective performance of
software documentation management can be seen as based on two elements as follows:
a) Management commitment to documentation: the recognition that software documentation is important and
must be planned, designed, developed, tested, reviewed, approved, distributed and maintained.
b) Management support:
1) guidance and incentives for staff to produce the required documentation,
2) provision of resources to facilitate the work.
3) evidence of managerial commitment and support
4.2 Evidence of managerial commitment and support
Managerial commitment to documentation should include provision and maintenance of several elements:
a) documentation policy statements,
b) standards and guidelines which have been identified for all aspects of software documentation,
c) published documentation procedures,
d) allocation of adequate resources to documentation,
e) inclusion of documentation planning as an integral part of the software life cycle,
f) continuous review to ensure compliance with, and improvement of, documentation policies, standards,
procedures and plans.
5 The functions of software documentation
5.1 Overview
To manage software documentation effectively, managers should be aware of the different functions
performed by software documentation, including user, development, and management documentation.
Software documentation can be regarded as having six major functions described in the following sub-
clauses: communication to management, communication among development task groups, quality assurance,
instruction and reference for users, communication for software maintenance, and reference for other projects.
2 © ISO/IEC 2005 – All rights reserved
---------------------- Page: 7 ----------------------
ISO/IEC TR 9294:2005(E)
5.2 Communication to management
During the development of software, management needs to be apprised of progress, problems and
expectations. Periodic reports, tracking progress against schedules and laying out plans for the next period,
provide control mechanisms and visibility for a project. Communication to management supports direction and
decisions on project continuation and resource allocation.
5.3 Task-to-task communication
Software development methodologies may need to establish formal documents for task-to-task
communication. Many software development projects are divided into tasks. These are often carried out by
different groups, such as specialists, analysts, designers, programmers, who need a means of communicating
with one another. For example, analysts may need to present formal requirements to designers, and
designers may need to give formal design specifications to programmers.
5.4 Quality assurance
Those charged with the responsibility for software quality assurance may need to establish formal documents
for both the software product and software quality assurance process required to carry out and document their
responsibilities and to meet the required quality of documentation for the software product.
Documentation is needed to enable those performing quality assurance activities to carry out their tasks.
NOTE Quality assurance activities should address both the software life cycle processes and their
documented products.
5.5 Instruction and reference
Documentation is needed to enable operators, users, acquirers, managers and other interested people to
understand and use the software product.
5.6 Software support
Maintenance programmers use the documentation containing detailed descriptions of the software to locate
and correct errors and modify the software as required.
Trainers and user support programmers may use the documentation for training and user support.
5.7 Historical reference
Documentation may be used as a historical reference for a other projects. This documentation can also be
used in the transfer and conversion of software to new environments.
6 Establishing documentation policies
Documentation policies prepared and supported by management provide guidance to all decision-makers.
Policies provide broad direction, and not detailed prescriptions on what to do or how to manage and prepare
documentation.
Formal, well-publicised policies should be written to establish the discipline required for effective software
documentation. Everyone affected by the policies should be informed of it and trained to effectively prepare
the documentation.
Policies should support the basic elements of effective documentation:
© ISO/IEC 2005 – All rights reserved 3
---------------------- Page: 8 ----------------------
ISO/IEC TR 9294:2
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.