ISO/IEC 6592:2000

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 2000
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
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
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
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
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
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
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
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
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
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
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
Figure 2 - Documentation profile
© ISO/IEC 2000 – All rights reserved
Document A =
Document B =
Document C =
Document D =
Document E =
Document F =
Document G =
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
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
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
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
System objectives are:
- external system effects
- requirements on system performance in producing deliverables, e.g. evaluation criteria.
212.1 Objective Name Objective Name Objective Name Name identifying specific system
objective.
212.2 Objective Objective Content Objective Content Description of system objectives and
Content purpose of the application.
212.3 Objective Objective Representation of higher level or lower
Hierarchy Hierarchy level system objectives (partial, individual
objectives; or main or related objective).
212.4 Range of Validity Range of Validity Range of validity of individual system
objectives.
212.5 Objective Objective Conflicting objectives, where achievement
Conflicts Conflicts of one objective hinders achievement of
another objective.
212.6 Completion Date Completion Date Point in time at which particular objective
was achieved, or is to be achieved.
212.7 Degree of Degree of Statement of degree a particular objective
Accomplishment Accomplishment was achieved, or is to be achieved.
212.8 Performance Statement of indicators to be used for
Indicators measurement of achievement of objective.
212.9 Weighting Methods for determination of priorities of
objectives and statement of objective
priorities.
© ISO/IEC 2000 – All rights reserved
Information Item Content
Item
No. level 1 level 2 level 3 Information Item
22 Detailed Requirements
Description of the physical/logical system to be realized by software development.
221 Functional Requirements
Functional requirements include all logical functions to be supported by the system, independent of their
technical realization.
221.1 Task Name Task Name Task Name Brief, application-oriented description of
tasks being solved, or to be solved by
software.
221.2 Task Hierarchy Task Hierarchy Hierarchical structure of tasks, subtasks.
221.3 Task Description Task to be solved by the software should be
described in generally understandable form.
In particular describe processing rules and
their logical and time dependencies.
221.4 Methods Methods Brief description of theories and methods
of computation used for solving tasks.
221.5 Theoretical State theoretical foundations for problem
Foundations solution. Describe essential steps of
methods used.
221.6 Units of State units of measurement and terms used.
Measurement
221.7 Task Limitations Task Limitations Limits of scope of application of software,
especially task oriented requirements and
restrictions.
221.8 Boundary State technical, computational or regulatory
Conditions related limits of application.
221.9 Processing Time State maximum time allowed for
processing of a task.
221.10 Reference to Reference to Laws Reference to Laws State references to laws, standards,
Laws and and Regulations and Regulations guidelines, ordinances, regulations,
Regulations restrictions which are, or may become, part
of the functional requirement.
221.11 Laws and Identify and, if necessary, interpret
Regulations important parts of laws, standards,
guidelines, ordinances, regulations which
have, or will have, a bearing on software,
including sources. Indicate deviations.
© ISO/IEC 2000 – All rights reserved
Item Information Item Content
No. level 1 level 2 level 3 Information Item
222 Data
State all data required by the system.
222.1 Data Name Data Name Data Name If necessary, state application oriented data
name, separated as input and output data.
222.2 Data Content Data Content Data Content State actual content of data, if necessary, by
naming data groups with reference to data
protection requirements.
222.3 Data Hierarchy Data Hierarchy Show data structure, e.g. hierarchy.
222.4 Data Source/ Data Source/ State data sources. Recipients of data; if
Recipient Recipient necessary, refer to data groups and
individual data.
222.5 Data Group Name Data Group Name State application oriented names of data
groups.
222.6 Data Group Data Group State actual content of data groups, if
Content Content necessary, by stating data items with
reference to data protection requirements.
222.7 Data Group Use Data Group Use State use of data groups as applied to
problems, e.g. data usage matrix.
222.8 Data Relationships State relations between data groups, data
items and tasks, e.g. input/output matrix,
decision table.
222.9 Data Item Name State application oriented name of
individual data items.
222.10 Data Item Content State actual content, if necessary, value of
individual data items, e.g. constant with
reference to data protection requirements.
222.11 Data Item Use State how a data item is used in the
solution, e.g. parameters, constants.
222.12 Data Volumes Data Volumes Data Volumes State volume of data to be processed.
222.13 Data Input State frequency and time distribution of
Frequencies input data, with data quantities.
222.14 Data Growth State expected growth in data volumes
within specific time frames.
© ISO/IEC 2000 – All rights reserved
Item Information Item Content
No. level 1 level 2 level 3 Information Item
223 Availability Characteristics
Availability characteristics are mainly numerical quantities indicating availability of the system, e.g.,
frequency, time distribution.
223.1 System System State times, or time periods (e.g. times of
Availability Availability day) when system must be available for
use.
223.2 Response Time State maximum time allowed for system to
produce results, or partial results, e.g.
dialogue replies.
223.3 Schedules/ State time frame when system results must
Deadlines be available.
224 Constraints
Constraints include security, privacy, safety, useability.
224.1 Physical Requirements for formulation of solution
Constraints based on organization and facilities
available in target environment.
224.2 Technical Requirements based on information
Constraints technology available.
225 Terminology
225.1 Terms List of application specific information and
definitions used in the documents.
225.2 Descriptors Keywords characterizing the described
system and its unique properties and which
can be used as search terms.
226 Information Model
226.1 Methods Methods Brief description of theories and methods
of information modeling used for solving
system information requirements.
226.2 Theoretical State theoretical foundation for information
Foundations modeling. Describe data objects, naming
conventions and data relationships.
226.3 Database/ Describe the organization of functional data
Data Dictionary objects structure for the database/data
dictionary management system.
© ISO/IEC 2000 – All rights reserved
Item Information Item Content
No. level 1 level 2 level 3 Information Item
23 System Components
Description of the system components fulfilling the requirements as planned or of existing software.
231 System Organization
2311 Structure Structure Indicate general structure of the system.
2312 Interfaces Interfaces Describe interfaces to other systems and
between system components.
232 Software Components
2321 Software Organization
2321.1 Software Name Software Name Software Name Name for identification of software used
during development, distribution and use. If
necessary distinguish through abbreviated
names (e.g. used in external or internal
correspondence) or during a specific time
interval. If the software is part of a software
system, the system name should also be stated.
2321.2 Alias Designation Alias Designation In addition to software, names of several
software aliases (in use at the same time) can
be differentiated, e.g. in connection with
differing sets or under different applications.
If necessary, different parts of the documents
may deal with different aliases.
2321.3 Version Version Version In addition to software name and alias
designation, distinguish between several
versions/variants of the software or its aliases.
Documents should describe the state of the
valid version/variant.
2321.4 Release Release Release Name of release of the first and currently valid
version/variant.
2321.5 Release Date Release Date Release Date Date of release of the first and currently valid
version/variant.
2321.6 Call Name Call Name Statement of software call name used in a
programming language, design language
(pseudo code) or in free form.
2321.7 Calling Conditions for correct calling of software, e.g.,
Requirements permitted parameter combinations, events or
triggers.
2321.8 Input Name Input Name Input Name State application oriented name of input. A
distinction is made between input data already
stored and are processable as a database, and
data to be processed.
2321.9 Input Objective Input Objective Description of input objectives.
2321.10 Input Detail In addition to statements about data
organization (No. 2322), the required access
algorithm and rules should be described or
named. This is also required for commands,
control instructions and functions. It should be
stated whether and what initial values are
entered by the software for the static data. For
formatted inputs, the data sequence should be
specified. For the purpose of clarification,
examples should be provided. For
unformatted inputs, input conventions should
be stated, such as:
- separators and their function,
- keywords for data identification,
- null values.
© ISO/IEC 2000 – All rights reserved
Item Information Item Content
No. level 1 level 2 level 3 Information Item
2321.11 Output Name Output Name Output Name State application oriented name of output.
A distinction is made between data to be
stored for further processing and data to be
used outside the software systems, e.g.
lists, screens, graphics and control
commands for control of technical
processes.
2321.12 Output Objective Output Objective Description of output objectives.
2321.13 Output Detail In addition to the statements about
organization (No. 2322), data intended for
use outside of software systems (e.g., user
messages) should be described by output
examples (e.g., printouts) with appropriate
interpretation aids, or by rules describing
their formation.
2321.14 Transmitted Data Description of data transmitted without
change.
2321.15 Software Software Function Software Function Summary description of software functions
Function and user interfaces.
2321.16 Data Flow Data Flow Data flow should be shown, if necessary, in
Description Description several detailed levels, e.g., by data flow
diagrams. All input and output data and all
data transmitted (e.g., messages) between
software modules should be recorded as to
meaning, time sequence, data carrier and
input and output devices.
2321.17 Software Software The internal execution sequence should be
Execution Execution described, if necessary, in several detailed
Sequence Sequence levels; software modules, subroutines,
branches, loops and, if necessary,
synchronization sectors should be shown.
Descriptive means include:
-flowcharts,
- decision tables,
- structure charts.
Descriptive means can be combined, if this
is useful for software description. The
execution description should permit
continuous forward and backward tracing
of software flow; cross-references to source
software and class of functions are
required.
2321.18 Algorithms Description of method of solution and of
algorithms, shown in connection with
problem statement and with software
construction. Name methods used in
software construction.
2321.19 Key to Codes Description of formats and meanings of
Used codes used. Show system of construction
and admissible values.
2321.20 Error Handling Show error checking tests and state
available error messages and resulting
actions.
2321.21 Mode of Operation Show mode of operation, e.g., batch,
online, real-time operation.
© ISO/IEC 2000 – All rights reserved
Item Information Item Content
No. level 1 level 2 level 3 Information Item
2321.22 Software Structure Software Structure Structuring of software in terms of software
elements (e.g. programs, subroutines,
modules, procedures, common
modules/procedures) in relation to problem
solution (see No. 2321.14). This
structuring can be shown graphically or
textually.
2321.23 Software Blocks Software Blocks A list should show names, points of entry
and interfaces of software blocks and their
relationships.
2321.24 Operating System Operating System Operating System State maker, name, release and version of
operating systems the software can run
under, without modification.
2321.25 Other Software Other Software Other Software State maker, name, release and version of
all other software required, e.g. auxiliary,
communication programs or other software
products required for use of the software.
2321.26 Programming Unambiguous designation of programming
Language language(s) used, including manufacturer,
release and version.
2321.27 Development/ State required tools (e.g. CASE tools,
Execution Tools compilers, assemblers or interpreters)
including manufacturer, release and
version.
2321.28 Source Code Sequence of instructions and declarations
(e.g. initial values and constants) or rules in
source language including comments, in
the form required by the compiler,
assembler, interpreter or commercial off-
the-shelf software. Source code can also be
part of the listing generated by the
compiler, assembler or interpreter.
2321.29 Translator Lists Documentation provided by compiler,
and Link Lists assembler or interpreter and link software,
showing translation from source code to
loading and runtime form. If possible (for
purposes of testing, error detection and
maintenance) the following (or reference to
their location) should be provided:
- listing of compiled, assembled or
interpreted software, including error
documents,
- listing of symbolic addresses and storage
allocations,
- listing for backwards tracing of address
references,
- listing of address references for loading.
2321.30 Software Size Software Size Total software size in commonly used
units, e.g. bytes, lines of source code.
Estimate size, if necessary.
2321.31 Costs Costs Costs State acquisition costs, e.g., purchase/rental
price, and operating costs (maintenance
costs) of software. Estimate costs, if
necessary.
© ISO/IEC 2000 – All rights reserved
Item Information Item Content
No. level 1 level 2 level 3 Information Item
2322 Data Organization
2322.1 File Name File Name File Name Statement of names for file identification,
especially:
- application oriented name,
- name under which operating system links
software with files,
- if necessary, name of database which
stores data.
2322.2 File Content
...