ISO/IEC 6592:2000
(Main)Information technology — Guidelines for the documentation of computer-based application systems
Information technology — Guidelines for the documentation of computer-based application systems
Technologies de l'information — Principes généraux relatifs à la documentation des systèmes d'application informatisés
General Information
Relations
Standards Content (Sample)
INTERNATIONAL ISO/IEC
STANDARD 6592
First edition
2000-03-15
Information technology — Guidelines for
the documentation of computer-based
application systems
Technologies de l'information — Principes généraux relatifs à la
documentation des systèmes d'application informatisés
Reference number
ISO/IEC 6592:2000(E)
©
ISO/IEC 2000
---------------------- Page: 1 ----------------------
ISO/IEC 6592:2000(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 2000
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 2000 – All rights reserved
ii
---------------------- Page: 2 ----------------------
ISO/IEC 6592:2000(E)
Contents Page
1 Scope.1
2 Normative references .2
3 Terms and definitions.2
4 Use of this International Standard .2
4.1 Purpose of documentation.3
4.2 Principles of documentation.3
4.3 Application of this International Standard to a software system.3
4.3.1 General application.3
4.3.2 Specification of document contents .4
4.3.3 Review of existing document contents .4
4.4 Constraints .4
4.5 Customization .5
5 Documentation method.5
5.1 Overview of the description of information items .5
5.2 Documentation profile.5
5.3 Description of information items.5
5.4 Detailed description of information items.11
Annex A (informative) Example of a documentation profile.28
Bibliography .31
© ISO/IEC 2000 – All rights reserved
iii
---------------------- Page: 3 ----------------------
ISO/IEC 6592:2000(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 6592 was prepared by Joint Technical Committee ISO/IEC JTC 1, Information
technology,SubcommitteeSC7, Software engineering.
This first edition cancels and replaces ISO 6592:1985, which has been technically revised.
Annex A of this International Standard is for information only.
© ISO/IEC 2000– All rights reserved
iv
---------------------- Page: 4 ----------------------
ISO/IEC 6592:2000(E)
Introduction
Documentation is essential to the success of any software development project. Management should determine
the quantity and content of documents to ensure there is neither too little nor too much. However, the most
important factor is to include all relevant information for the users. This International Standard provides a method
to define an adequate set of documents to use throughout the life cycle of a software development project,
including its definition and use.
© ISO/IEC 2000 – All rights reserved
v
---------------------- Page: 5 ----------------------
INTERNATIONAL STANDARD ISO/IEC 6592:2000(E)
Information technology — Guidelines for the documentation of
computer-based application systems
1 Scope
This International Standard gives guidelines for the documentation of information systems (ISs) and is intended for
use in that area. This International Standard is applicable to the software of IS. However, some aspects of
hardware, e.g. configuration of the system, are included.
This International Standard is not intended to be a guide to the way documents are organized or structured.
Instead, it provides a checklist for two parties to use in agreeing on document content.
The guidelines given in this International Standard have been developed with the objectives of:
� obtaining the necessary commitment of the parties involved with the life cycle of the IS to participate in
the development process;
� contributing to the production of well-planned, standardized software system documents;
� enabling the production of software system documents in parallel with the software life cycle.
Well-defined rules for documents during the software life cycle facilitates:
� the provision of relevant information;
� the preparation of the documentation itself;
� estimation of the time and resources required for the achievement of a project;
� exchange of information between parties concerned, resulting in:
- selection of attainable objectives for a system;
- a more complete and well-considered functional design;
- fewer misunderstandings and mistakes;
� making decisions and briefing of personnel during the software life cycle.
This International Standard is designed to be applicable to the whole range of ISs and recognizes the software
component of a system may vary from a minor part to a major complex component.
This International Standard applies to documents in any natural language or representation and is independent of
the medium used for its implementation, i.e., the principles are generally applicable, but in some cases there may
be differences in structure and format.
Although this International Standard is intended mainly for use in the software engineering (SE) area, there will be
other groups involved less directly with SE including those involved in SE strategy, people with SE requirements,
SE customers and SE users. This International Standard is relevant to those groups. The groups will produce
some of the documents (e.g., strategy, customer requirements and user documents).
Associated with SE activities are methods, techniques and tools. Many of these products have their own
documentation facilities. Software engineers may use documents of this type, but should ensure the principles and
practices given in this International Standard are observed.
© ISO/IEC 2000 – All rights reserved
1
---------------------- Page: 6 ----------------------
ISO/IEC 6592:2000(E)
2 Normative references
This International Standard has no normative references. Informative references are listed in the bibliography.
3 Terms and definitions
For the purposes of this International Standard, the following definitions apply.
3.1
document
uniquely identified unit of information for human use, such as a report, specification, manual or book
3.2
documentation
collection of one or more related documents
3.3
information item (sub-item)
defined group of elements of information
NOTE A sub-item is a part of an information item.
3.4
documentation profile
table of information items describing the content of one or more documents
3.5
conditional
information supplied with every package to which it is relevant
3.6
optional
information supplied at the discretion of the manufacturer or marketing organization
4 Use of this International Standard
This International Standard may be used for documents in a wide variety of SE areas. Its primary use is
documenting software systems during development, but it may also be of use to document other aspects of the life
cycle, e.g. system maintenance, system operation and organization (project teams and human resources).
This International Standard supports the preparation of documents for any life cycle model and is independent of
the model or methodology.
For a life cycle with a series of interrelated phases where documents provide the means of communication between
adjacent phases, documentation provides a record of the work done up to that point.
For an iterative life cycle, where some development processes are repeated before a deliverable is produced,
documents may reflect increasing detail as iterations are carried out, or the level of detail may remain constant.
For parallel or model-driven life-cycle development, where separate teams are working in parallel to develop
aspects of the total software system, documentation forms the communication between teams or models and
specifies the information items used to communicate information and the required level of detail.
Guidance on life-cycle processes is provided in ISO/IEC 12207. If that International Standard is complied with,
some tailoring of the information items listed in this International Standard may be needed.
© ISO/IEC 2000 – All rights reserved
2
---------------------- Page: 7 ----------------------
ISO/IEC 6592:2000(E)
4.1 Purpose of documentation
There are four main purposes of documenting:
� Describe and record information about a system throughout its life cycle.
� Assist the usability and maintainability of the IS.
� Help control the life-cycle process.
� Communicate information about the system to those who need it.
4.2 Principles of documentation
The primary principle of documenting should be to identify all types of users of the system's documents — "user" in
this context includes not only the end-users of the software, but also developers, testers and other people who use
the documents prepared during the development process.
Having identified all of the different types of users (this International Standard refers to these users later as
"audiences"), it is then necessary to think about their information needs. Different end-user audiences will have
different information needs, and different developer audiences will also have different needs, depending on the
tasks they will perform. The information should then be translated into a set of "information items" matching, if
possible, those given in 5.4.
There are a number of well-developed documentation methodologies to help with this process. This International
Standard does not depend on the use of any particular methodology. Documents satisfying user needs require
planning.
Having reached agreement on a list of information items, use a documentation profile to map those information
items to specific documents. The documents described in this International Standard may be recorded on any
medium. Some documentation methodologies will assist in deciding on the appropriate document medium, layout
and structure.
4.3 Application of this International Standard to a software system
4.3.1 General application
To apply this International Standard, the information requirements of the users of the documents should be
determined. These requirements should be specified in a documentation profile (see 5.2) using the description of
information items (see 5.3 and 5.4).
The preparation of a documentation profile is essential to establish the contents of the documents forming the
complete set of system documentation. The customer and supplier should agree to the profile so there is prior
understanding of the contents of the documentation set to be delivered to the customer.
The development of the documentation profile will enable both parties to agree on document titles and contents.
The content and the complexity of the documents will depend on the application of the software system and the
audience for the documents specified in the profile.
Information items to review in determining the content and the complexity of the documents are presented in three
levels. These levels may be used in a variety of ways, such as the following:
� Level 1 information items may be required in summary documents or early in the life cycle. Levels 2 and
3 information items may be required in more detailed documents or later in the life cycle.
� Level 1 information items may be the only ones required in simple systems where detailed documents
are not needed.
� Levels 2 and 3 information items may be required for software systems considered more critical and
sensitive than other software systems.
This International Standard may be used either to define specific types of documents and their contents, or to verify
an existing set of document types conforms to this International Standard.
© ISO/IEC 2000 – All rights reserved
3
---------------------- Page: 8 ----------------------
ISO/IEC 6592:2000(E)
4.3.2 Specification of document contents
The following steps should be carried out to complete a documentation profile:
I. Identify the documents needed throughout the life cycle. The names of these documents should be listed
across the top of the columns on the documentation profile (columns 4 to n).
II. Review the contents of each information item to determine if it is required in that document. Identify whether
the information is essential (E), conditional (C) or optional (O).
Check the information items at the different levels of the description of information items to determine which level is
necessary for the document and insert the code (E, C or O) into the required level in the documentation profile.
It is recommended that contents be clarified by the use of examples.
In certain circumstances it is acceptable to define a document by listing the information items and/or sub-items
included in a document of that type, rather than by completing a documentation profile for that document. This
would be appropriate for instance where a customer wishes to define a checklist for the contents of a document
forming part of the contractual deliverable for a software project.
Alternatively, a list of items and sub-items could be used to define a document not containing the precise mix of
sub-items identified in this International Standard for a given level of detail.
4.3.3 Review of existing document contents
This International Standard may also be used to review the documents from an existing documentation set to
determine their compliance with this International Standard.
This process can help verify the documents from an existing documentation set conform to this International
Standard or may identify information items missing from those documents. The review may be carried out in the
following manner:
I. Prepare a comparison matrix with the paragraph numbers and titles of the existing documents listed down
one side and a column on the other side into which will be inserted the item number(s) of the information
item(s) from the description of information items (see 5.4).
II. Identify an information item (usually a paragraph title or item within a paragraph) in the existing
documentation set and review the list of information items in the description of information items (see 5.4).
III. Identify which information item(s) match the information item in the existing documentation set. Insert the
item number(s) of the matching information item(s) into the column beside the matching paragraph number
and title from the existing documentation set.
NOTE Several item numbers may relate to one paragraph number and title in the existing documentation set.
IV. Note any information items in the existing documentation set having no corresponding information item from
this International Standard.
V. Review the other information items from this International Standard to ensure all necessary information items
are included in the documents from the existing documentation set.
4.4 Constraints
A particular document or information item may have no relevance to one system and yet be important to another.
The documentation profile developed through use of this International Standard should be used to ensure, if
information is omitted from the documentation, the omission is the result of a positive decision and not an oversight.
© ISO/IEC 2000 – All rights reserved
4
---------------------- Page: 9 ----------------------
ISO/IEC 6592:2000(E)
Therefore, in applying this International Standard, the following guidelines should be observed constraining use of
information items in documents produced:
� Completeness: Each information item required by the documentation profile should be included in the
documentation set for a system or a reason should be given why it was not included.
� Relevance: There should be justification for including a given information item in the documentation
profile for a particular document.
� Level of detail: For a given information item different levels of detail may occur in the same document.
With time and in successive documents there should be a progression from less to more detail as a
matter of principle.
4.5 Customization
This International Standard defines a framework in which documents are defined by using a hierarchical profile to
define information items for software system documents and concentrates on information items mainly for program
and data development. It is not intended to restrict information items to those listed in this International Standard.
This International Standard can be tailored by adding, altering or deleting information items as necessary as long
as the same framework is used.
5 Documentation method
5.1 Overview of the description of information items
The overview is presented as a tree-structured list (see Figure 1). The list contains the name and item number of
the information items detailed in the description of information items (see 5.3 and 5.4).
The item numbers and names shown under the heading “Structure” are group and sub-group headings for the
“Information Items” identifying specific information.
5.2 Documentation profile
The documentation profile form (see Figure 2) is provided as a template for creating a documentation profile for a
software system.
In the documentation profile, the matrix is divided into a number of columns. Each document required for the
software system is represented by a column (e.g. A,B,C). See Annex A for an example of how to identify the
documents portrayed in Figure 2.
When completed, the documentation profile can be used to develop a documentation plan and to check that the
software system is documented to the correct level of detail.
5.3 Description of information items
The information for the preparation of documents is derived from information items. An information item may
comprise a number of sub-items depending on the degree of detail required to describe the item. The sub-items
are listed in a hierarchy, the basis for the numbering convention used for information items.
This numbering convention is as follows:
� Each heading has a number to indicate its position in the hierarchy (see Figures 1 and 3).
� Each information item has an item number that may be up to four digits (see Figure 1).
� Each sub-item has an item number comprising the information item number plus a further number
separated by a decimal point (e.g. 2311.5).
© ISO/IEC 2000 – All rights reserved
5
---------------------- Page: 10 ----------------------
ISO/IEC 6592:2000(E)
Information items are grouped and denoted by headings. A heading includes a number appropriate to its place in
the structure. Following the number is the name of the group (may include a short description - see Figure 4).
After the headings, the information items are each proceeded by its item number. The item number provides the
classification for the item and its position in the hierarchy. Information items occur in two forms:
I. A single information item comprises its item number, its item name and its item content (see Figure 4). A
single information item may either be present in or absent from a document, but may not occur at varying
levels of detail.
II. A compound information item consists of a number of sub-items, each comprising its item number, its item
name and its item content. A compound information item can therefore occur at varying levels of detail in a
document. The degree of detail in the compound information item is expressed by combining the sub-items
appropriate to the level required (see Figures 4, 5 and 6). In this International Standard a compound
information item consists of two or three levels of detail (see Figure 4).
Shaded columns in Figures 4, 5 and 6 indicate no further levels of detail are expected. In this case, the required
details should be given at level 1 or level 2.
Columns (level 1, level 2 or level 3) indicate the levels of detail. For a compound information item, level 2 includes
all sub-items from level 1 plus some additional sub-items. Similarly, level 3 includes all sub-items from level 2 plus
all remaining sub-items for that compound information item.
That means (see Figure 4, 5 and 6):
� Level 1 information items include all sub-items named in the column "level 1" of the information item;
� Level 2 information items include all sub-items named in the column "level 2" of the information item;
� Level 3 information items include all sub-items named in the column "level 3" of the information item.
With time and in successive documents, a compound information item may occur in increasing detail by including
additional sub-items of information on that subject.
This gradual change in the level of detail may necessitate revision of documents produced earlier in the software
life cycle. Sub-items themselves (or indeed unitary information items) do not therefore necessarily remain identical
in content throughout the life cycle. Experience gained during a project may require that information is corrected or
adjusted to reflect the better understanding of the software system that experience has given.
Where the sub-item name occurs across two or more levels (e.g., 212.1 Objective Name), the value of the sub-item
may be the same at all levels or may be expanded at level 2 and level 3 if necessary.
A document can therefore comprise information items at different levels of detail depending on the requirements
specified in the documentation profile.
© ISO/IEC 2000 – All rights reserved
6
---------------------- Page: 11 ----------------------
ISO/IEC 6592:2000(E)
Structure Information Item
11 Problem Definition
12 Objectives
13 Justification for Proposal
1 System Requirement 14 Document References
15 Constraints
16 Language
17 Contractual Information
2 System Description 21 System Identification 211 System Name
212 System Objectives
221 Functional Requirements
222 Data
22 Detailed Requirements 223 Availability Characteristics
224 Constraints
225 Terminology
226 Information Model
23 System Components 231 System Organization 2311 Structure
2312 Interfaces
232 Software Components 2321 Software Organization
2322 Data Organization
233 Physical Components 2331 Processing Units
2332 Data Peripheral Equipment
2333 Process Peripherals
2334 Other Equipment
2335 Supplies
2336 Accommodation/Inventory
24 Testing 241 Test Objectives
242 Test Methods and Tools
243 Test Cases/Benchmarks
25 Installation 251 Installation/Use
252 Training
26 Human Resources 261 Personnel
262 Organization
3 Evaluation Indicators 31 Costs/Benefits
32 Installation Experience
33 Strengths/Weaknesses
34 Evaluation Criteria/Methods
35 Evaluation Results
4 Conclusions/Recommendations 41 Decision
42 Justification
43 Responsibility
Figure 1 — Overview of the description of information items
© ISO/IEC 2000 – All rights reserved
7
---------------------- Page: 12 ----------------------
ISO/IEC 6592:2000(E)
11
12
13
14
15
16
17
211
212
221
222
223
224
225
226
2311
2312
2321
2322
2331
2332
2333
Figure 2 - Documentation profile
© ISO/IEC 2000 – All rights reserved
8
Document A =
Document B =
Document C =
Document D =
Document E =
Document F =
Document G =
---------------------- Page: 13 ----------------------
ISO/IEC 6592:2000(E)
Heading number and name
Compound heading,
(description is optional)
with related numbers
and names
Information item number and
(description is
name (description is optional)
optional)
Sub-item number
Levels 1, 2 and
Sub-item number and
3 information
name (description is
item names
optional)
Compound
information
item
Sub-item number
Level 1, 2 or 3
description
Figure 3 - Illustration of the description of information items
Heading
number and
name
Level 1
(description is
information
optional)
item names and
related
descriptions
Single information
item, with sub-item
level 1 name and
description
Compound
information item
number, with sub-
item (levels 1 and
2) names and
related descriptions
Figure 4 - Illustration of the 1st level of an information item
© ISO/IEC 2000 – All rights reserved
9
---------------------- Page: 14 ----------------------
ISO/IEC 6592:2000(E)
Level 2
information
item names and
related
descriptions
Figure 5 - Illustration of the 2nd level of an information item
Level 3
information
item names and
related
descriptions
Figure 6 - Illustration of the 3rd level of an information item
© ISO/IEC 2000 – All rights reserved
10
---------------------- Page: 15 ----------------------
ISO/IEC 6592:2000(E)
5.4 Detailed description of information items
The following presents the detailed description of information items.
Item Information Item Content
No. level 1 level 2 level 3 Information Item
1 System Requirement
Statement and delimitation of problem to
11 Problem
Definition be solved by the software under
development.
12 Objectives Statement of expected results from
software and requirements of software.
13 Justification for Motive and justification for proposal.
Proposal
14 Document List of document references for next phase
References of development, e.g. documentation of
current state.
15 Constraints Statement of requirements (e.g., conditions,
limitations, quality planning, security)
placed on development by an acquirer for
next phase, such as:
- means to be assigned, e.g., people,
material, funding,
- method of implementation,
- reporting period,
- completion date.
The languages used for the documents
16 Language
should be identified, e.g. Japanese, French,
English.
Contractual information should be
17 Contractual
specified. Copyright conditions, licensing
Information
terms, conditions of use and the terms of
warranty or guarantee should be stated.
The guarantor should be named.
© ISO/IEC 2000 – All rights reserved
11
---------------------- Page: 16 ----------------------
ISO/IEC 6592:2000(E)
Item Information Item Content
No. level 1 level 2 level 3 Information Item
2 System Description
21 System Identification
Name identifying system and if possible
211 System Name
any item number or product code.
System Objectives
212
System objectives are:
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.