ISO/IEC TR 9294:1990
(Main)Information technology — Guidelines for the management of software documentation
Information technology — Guidelines for the management of software documentation
Addresses the policies, standards, procedures, resources and plans to produce an effective software. Applicable to all types of software from the simplest program to the most complex software system and to all stages of the software lifecycle. Detailed advice on the content and layout of software documentation is not provided. Annex A contains checklists of the policies, standards, procedures and project planing on the software production.
Technologies de l'information — Lignes directrices pour la gestion de la documentation technique du logiciel
General Information
Relations
Buy Standard
Standards Content (Sample)
ISO/IEC
TECHNICAL
TR 9294
REPORT
First edition
1990-l 1-15
Information technology - Guidelines for the
management of software documentation
Lignes direc trices pour la ges tion de la
Technologies de l’informa tion -
documentation technique du logiciel
Reference number
ISO/IEC TR 9294 : 1990 (E)
---------------------- Page: 1 ----------------------
ISOAEC TR 9294 : 1990 (E)
Page
Contents
iii
Foreword. .
iv
Introduction. .
1
1 Scope .
1
2 References. .
........................................................ 1
3 Definitions
1
4 Theroleofmanagers .
2
5 The functions of software documentation .
2
5.1 Communication to management .
2
5.2 Task-to-task communication .
2
5.3 Qualityassurance .
2
5.4 Instruction and reference .
2
...................................................
5.5 Softwaresupport
2
5.6 Historical reference
.................................................
2
6 Establishing documentation policy .
.................... 3
7 Establishing documentation standards and guidelines
3
7.1 Selecting a software lifecycle model .
3
7.2 Defining document types and content .
4
7.3 Defining document quality .
4
7.4 Defining document formats .
5
7.5 Defining a document identification system .
5
8 Establishing documentation procedures. .
................................ 5
9 Allocating resources to documentation
5
9.1 People .
5
9.2 Facilities .
5
Funding .
9.3
5
10 Documentation planning .
Annex A Checklists for software documentation management
7
A.1 Policy checklist .
................................................. 7
A.2 Standards checklist
7
A.3 Procedures checklist .
A.4 Project planning checklist . 7
0 ISO/IEC 1990
All rights reserved. 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 the publisher.
ISO/IEC Copyright Office l Case postale 56 l CH-1211 Gen&e 20 l Switzerland
Printed in Switzerland
ii
---------------------- Page: 2 ----------------------
lSO/IEC TR 9294 : 1990 (E)
Foreword
IS0 (the International Organization for Standardization) and IEC (the International
Electrotechnical Commission) together form a system for worldwide standardization as
a whole. National bodies that are members of IS0 or IEC participate in the develop-
ment of International Standards through technical committees established by the
respective organization to deal with particular fields of technical activity. IS0 and IEC
technical committees collaborate in fields of mutual interest. Other international
organizations, governmental and non-governmental, in liaison with IS0 and IEC, also
take part in the work.
In the field of information technology, IS0 and IEC have established a joint technical
committee, ISO/IEC JTC 1.
The main task of a technical committee is to prepare International Standards but in
exceptional circumstances, the publication of a technical report of one of the following
types may be proposed:
when the necessary upport within the techn ical committee ca nnot be
- type 1,
fo r the publication of a International Standard,
obtained despite repeated efforts;
when the subject is still under technical development requiring wider
- type 2,
exposure;
- type 3, when a 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 publica-
tion, 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.
ISOAEC TR 9294, which is a technical report of type 3, was prepared by ISO/IEC
JTC 1, Information technology.
---------------------- Page: 3 ----------------------
lSO/IEC TR 9294 : 1990 (E)
Introduction
Documentation is required for all stages of the software lifecycle. As a result, the
preparation and maintenance of documentation constitutes a necessary and con-
tinuous effort from the inception of the software through to its disposal. Documen-
tation begins with the initiation of a software project and continues with the design,
development, testing, installation, use, modification and enhancement of the soft-
ware. The documentation process can only be regarded as having ended when the
software comes to the end of its life.
Documentation is essential for the success of any software development project, and
the production of documentation requires the commitment of time, effort and money.
It is the responsibility of management to ensure the effective deployment of these
resources, recognizing the importance of documentation to the quality and success of
the software product.
---------------------- Page: 4 ----------------------
ISO/lEC TR 9294: 1990 (E)
TECHNICAL REPORT
Information technology - Guidelines for the management
of software documentation
3.2 documentation: A collection of one or more related
I Scope
documents.
This Technical Report offers guidance on the management of
software documentation to those managers responsible for the
3.3 software product: The result of the software develop-
production of software or software-based products. The
ment process, i.e. software that has been released for use.
guidance is intended to assist managers in ensuring that effec-
tive documentation is produced in their organization.
The report addresses the policies, standards, procedures,
resources and plans which managers must concern themselves
4 The role of managers
with in order to manage software documentation effectively.
Managers commit their organization to documentation effort
The guidance given is intended to be applicable to all types of
and give support to that effort in the policies, standards, pro-
software, from the simplest program to the most complex
cedures, resource allocations and plans that they establish.
software suite or software system. All types of software
documentation are covered, relating to all stages of the soft-
Effective performance of the managerial role can be seen as
ware lifecycle.
resting on three elements:
The principles of software documentation management are the
1) Management commitment to documentation
same whatever the size of the project. For small projects, much
of the detail given in this report may not apply, but the prin-
This commitment requires recognition that software
ciples remain the same. Managers may tailor the recommen-
documentation is important and that it must be planned,
dations to their particular needs.
written, reviewed, approved, produced, distributed and
maintained.
It should be stressed that the guidance given is from the point
of view of documentation management. Detailed advice on, for
2) Management support of staff commitment to
example, the content and layout of software documents is not
documentation
provided.
This requires guidance and incentives for staff to produce
the required documentation and the provision of resources
to facilitate the work.
2 References
3) Evidence of managerial commitment and support
IS0 2382 : 1984, Data processing - Vocabulary - Part 7: Fun-
This requires the provision of
damen tal terms.
a) published documentation policy statements;
I SO 6592 : 1985, Information processing - Guidelines for the
documentation of computer-based application systems.
b) standards and guidelines identified for all aspects of
software documentation;
IS0 9127 : 1988, Information processing systems - User
documentation and cover information for consumer software
c) published documentation procedures;
packages.
d) the allocation of adequate resources to documen-
tation ;
3 Definitions
e) documentation planning undertaken as an integral
For the purposes of this Technical Report, the following defi-
part of the software development process;
nitions apply.
f) continuous review undertaken to ensure compliance
with documentation policy, standards, procedures and
3.1 document: A uniquely identified unit of information for
plans.
human use, such as a report, specification, manual or book.
---------------------- Page: 5 ----------------------
ISO/IEC TR 9294 : 1990 (E)
5.5 Software support
5 The functions of software documentation
To manage software documentation effectively it is important
Maintenance programmers require detailed descriptions of the
to be aware of the different functions performed by documen-
software so that they can locate and correct errors, and
tation.
enhance or change the software as required.
Software docu mentation can be regarded as having six major
functions
5.6 Historical reference
Communication to management (see 5.1).
1)
Documentation is needed as a historical reference for the proj-
2) Task-to-task communication (see 5.2).
ect. This documentation can also assist in the transfer and con-
version of software to new environments.
3) Quality assurance (see 5.3).
Instruction and reference (see 5.4).
4)
Software support (see 5.5).
5)
6 Establishing documentation policy
Historical reference (see 5.6).
6)
Documentation policies that are prepared and supported by
5.1 Communication to management
senior management provide guidance to decision-makers at all
lower levels. Policy provides broad direction, but not detailed
During the development of software, management needs to be
prescriptions on what to do or how to do it.
apprised of progress, problems and expectations. Periodic
reports that track progress against schedules and lay out plans
Because of the vital role documentation plays at all stages of
for the next period provide control mechanisms and visibility for
the software lifecycle, a formal statement of policy should be
the project.
prepared. Everyone affected by the policy should be informed
of it and should understand it. Formal, written, well-publicized
. Task-to-task communication
52 policy establishes the discipline required for effective software
documentation.
Most softwa re development projects are divided into tasks,
often carried out by different groups. Typically
Policy should support the basic elements of effective documen-
tation :
* subject area specialists initiate the project
* analysts formulate system requirements
n requirements
1) Docu mentatio cover
software lifecycle
* designers develop system and program designs
* publications specialists #reduce user documentation in
P Documentation is required during the early stages of a proj-
conformance wi th policy an d standa rds for documentation
ect, and must be available and maintained throughout the
software development process. After the development is
a assess
* quality assurance specialists and
completed, documentation is needed for the use, mainten-
overall software integrity and performance
ance, enhancement, conversion or transfer of the software.
* maintenance programmers improve the operational
software and develop enhancements or extensions
Documentation should be managed
2)
Direction and control are required to obtain and maintain
These people need a means of communicating with one another
documentation. Managers and publications specialists
which provides information that can be reproduced, distributed
should prepare detailed plans outlining documentation
and referred to as needed.
products, schedules, responsibilities, resources, and quality
Most software development methodologies establish formal assurance and review procedures.
documents for task-to-task communication. For example,
analysts present formal requirements specifications to de-
3) Documentation should be appropriate to its
signers, and designers give formal design specifications to pro-
readership
grammers.
Readers may be managers, analysts, professionals with no
computer expertise, maintenance programmers, clerical
5.3 Quality assurance
personnel, etc. Depending on tasks performed, they require
various degrees of detail and different presentations of
Those charged with the responsibility for quality assurance of
material. A publications specialist should be charged with
software require development and product documentation to
properly designing different types of documentation des-
carry out their tasks.
tined for different readers.
5.4 Instruction and reference
4) Docum entation effort should be integrated into
the overall
software development process
Documentation is needed to enable operators, users, managers
The development process should be defined.
and other interested persons to understand and use the soft-
ware product.
---------------------- Page: 6 ----------------------
ISO/IEC TR 9294 I 1990 (E)
model is
5) Documentation standards should be identified adopted so long as the stages and their associated
documen tation are clearly
and used defined, planned and scheduled for
any particular software project. Managers should, therefore,
Existing standards should be adopted wherever possible.
select an appropriate software lifecycle
and ensu re that it
Where no suitable s
...
ISOICEI
RAPPORT
TECHNIQUE TR 9294
Première édition
1990-11-15
Technologies de l’information - Lignes
directrices pour la gestion de la documentation
technique du logiciel
Guidelines for the management of software
Information technology -
documentation
Numéro de référence
ISOKEI TR 9294 : 1990 (FI
---------------------- Page: 1 ----------------------
ISO/CEI TR 9294 : 1990 (F)
Sommaire page
iii
Avant-propos. .
............................................................ iv
Introduction
................................................ 1
1 Domaine d’application
.......................................................... 1
2 Références
3 Définitions . 1
................................................
4 Rôle des gestionnaires 1
....................... 2
5 Les objet de la documentation technique du logiciel
..................... 2
5.1 Communication de renseignements à la direction
................
5.2 Communication entre les différents groupes d’activité. 2
........................................... 2
5.3 Assurance de la qualité
....................................... 2
5.4 Information et consultation
...............................................
5.5 Soutien du logiciel 2
............................................... 2
5.6 Dossier historique
................. 2
6 Etablissement de la politique concernant la documentation
7 Etablissement des normes et lignes directrices relatives à la documentation . 3
........................ 3
7.1 Choix d’un modèle de cycle de vie du logiciel
.. 4
7.2 Définition des catégories de documents et du contenu des documents.
7.3 Définition de la qualité des documents . 5
..................
7.4 Définition du mode de présentation des documents. 5
............
7.5 Définition d’un mécanisme d’identification des documents. 5
................. 6
8 Établissement des procédures relatives à la documentation
........................... 6
9 Affectation des ressources à la documentation
............................................
9.1 Ressources humaines 6
.................................................... 6
9.2 Installations
...........................................
9.3 Ressources financières 6
......................................
10 Planification de la documentation. 6
Annexe A Mesures à prendre pour assurer la gestion de la documentation
technique du logiciel
A.1 Mesures relatives aux lignes de conduite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
A.2 Mesures à prendre dans le domaine des normes . . . . . . . . . . . . . . . . . . . . . . . . .
8
A.3 Mesures à prendre dans le domaine des procédures . . . . . . . . . . . . . . . . . . . . . . 8
A.4 Mesures à prendre dans le domaine de la gestion du projet . . . . . . . . . . . . . . . . 8
@ ISOKEI 1990
Droits de reproduction réservés. Aucune partie de cette publication ne peut être reproduite ni
utilisée sous quelque forme que ce soit et par aucun procédé, électronique ou mécanique,
y compris la photocopie et les microfilms, sans l’accord écrit de l’éditeur.
ISOKEI Copyright office l Case postale 56 l CH-1211 Genève 20 l Suisse
Imprimé en Suisse
ii
---------------------- Page: 2 ----------------------
ISO/CEI TR 9294 : 1990 (F)
Avant-propos
L’ISO (Organisation internationale de normalisation) et la CEI (Commission électro-
technique internationale) forment le système spécialisé de normalisation mondiale. Les
organismes nationaux membres de I’ISO ou de la CEI participent au développement de
Normes internationales par l’intermédiaire des comités techniques créés par I’organisa-
tion concernée afin de s’occuper des différents domaines particuliers de l’activité tech-
nique. Les comités techniques de I’ISO et de la CEI collaborent dans des domaines
d’intérêt commun. D’autres organisations internationales, gouvernementales ou non
gouvernementales, en liaison avec I’ISO et la CEI participent également aux travaux.
Dans le domaine des technologies de l’information, I’ISO et la CEI ont créé un comité
technique mixte, I’ISOKEI JTC 1.
La tâche principale des comités techniques est d’élaborer les Normes internationales,
mais, exceptionnellement, un comité technique peut proposer la publication d’un
rapport technique de l’un des types suivants:
-
1, lorsque, en dépit de maints efforts, l’accord requis ne peut être réalisé
type
en faveur de la publication d’ ‘une Norme internationale;
-
type 2, lorsque le sujet en question est encore en cours de développement
technique ou lorsque, pour toute autre raison, la possibilité d’un accord pour la
publication d’une Norme internationale peut être envisagée pour l’avenir mais pas
dans l’immédiat;
-
type 3, lorsqu’un comité technique a réuni des données de nature différente de
celles qui sont normalement publiées comme Normes internationales (ceci pouvant
comprendre des informations sur l’état de la technique, par exemple).
Les rapports techniques des types 1 et 2 font l’objet d’un nouvel examen trois ans au plus
tard après leur publication afin de décider éventuellement de leur transformation en Nor-
mes internationales. Les rapports techniques du type 3 ne doivent pas nécessairement
être révisés avant que les données fournies ne soient plus jugées valables ou utiles.
L’ISOKEI TR 9294, rapport technique du type 3, a été élaboré par le comité technique
mixte ISOKEI JTC 1, Technologies de l’information.
. . .
III
---------------------- Page: 3 ----------------------
ISO/CEI TR 9294 : 1990 (F)
Introduction
La documentation technique est nécessaire à tous les stades du cycle de vie du logiciel.
En conséquence, l’élaboration et la tenue à jour de la documentation technique consti-
tuent des fonctions indispensables et permanentes à assurer à partir du moment où le
logiciel est créé jusqu’à sa mise au rancart. L’élaboration de la documentation techni-
que commence au moment du lancement d’un projet de logiciel et elle se poursuit au
fur et à mesure de la conception, du développement, de la mise à l’essai, de I’installa-
tion, de l’utilisation, de la modification et de l’amélioration du logiciel. Le traitement de
la documentation technique ne peut être considéré terminé que lorsque le logiciel par-
vient à la fin de sa vie utile.
La documentation technique est indispensable au succès de tout projet de création de
logiciel et la production de la documentation technique exige que l’on y engage du
temps, des efforts et des ressources financières. II est du devoir des gestionnaires de
veiller à investir ces ressources en toute efficacité, en tenant compte de l’importance
que revêt la documentation technique pour la qualité et la réussite du produit de
logiciel.
iV
---------------------- Page: 4 ----------------------
ISO/CEI TR 9294 : 1990 (F)
RAPPORT TECHNIQUE
Technologies de l’information - Lignes directrices pour la
gestion de la documentation technique du logiciel
3 Définitions
1 Domaine d’application
Pour les besoins du présent Rapport technique, les définitions
Le présent Rapport technique offre des conseils sur la gestion
suivantes s’appliquent.
de la documentation technique du logiciel aux gestionnaires
chargés de la création de produits logiciels ou de produits utili-
3.1 document: Unité d’information possédant son identité
sant les logiciels. Ces conseils visent à faciliter aux gestionnai-
propre et lisible par l’homme, par exemple un rapport, un cahier
res la tâche de veiller à l’élaboration d’une documentation tech-
des charges, un guide ou un livre.
nique efficace au sein de leur organisation.
3.2 documentation: Collection constituée d’un ou de plu-
II traite des politiques, des normes, des procédures, des
sieurs documents connexes.
ressources et des plans qui méritent de retenir l’attention des
gestionnaires désireux de gérer en toute efficacité la documen-
tation technique du logiciel.
3.3 produit de logiciel: Résultat du processus de création
de logiciels, c’est-à-dire logiciel lancé pour fin d’utilisation.
Les directives données dans le présent Rapport technique sont
censées être applicables à toutes les catégories de logiciel, à
partir du programme le plus simple jusqu’au progiciel le plus
4 Rôle des gestionnaires
complexe. On y traite de toutes les catégories de documenta-
Les gestionnaires amènent leur organisme à s’engager dans un
tion technique du logiciel, par rapport à tous les stades du cycle
de vie du logiciel visé. travail de documentation qu’ils appuient dans les politiques, les
normes, les procédures, les affectations de ressources et les
plans qu’ils établissent.
Les principes qui sous-tendent la gestion de la documentation
technique du logiciel sont les mêmes, peu importe l’envergure
Pour évaluer dans quelle mesure les gestionnaires s’acquittent
du projet. En ce qui a trait aux petits projets, il se peut qu’une
du rôle qui leur revient sous ce rapport, on peut se fonder sur
grande partie des détails énoncés dans le présent Rapport tech-
les trois éléments suivants :
nique ne soient pas applicables, mais les principes demeurent
les mêmes. Les gestionnaires pourront adapter à leurs besoins
1) Intérêt des gestionnaires à l’égard de la documen-
particuliers les recommandations qui y sont faites.
tation
Les gestionnaires doivent reconnaître que la documentation
À noter que les directives données dans le présent Rapport
technique est importante et qu’elle doit être planifiée, rédi-
technique sont concues dans la perspective de la gestion de la
gée, examinée, approuvée, produite, distribuée et tenue à
documentation technique. II n’y est pas donné de conseils
jour.
détaillés sur le contenu ni sur le mode de présentation des
documents concernant les logiciels.
2) Appui des gestionnaires à l’intérêt manifesté par
leurs employés à l’égard de la documentation techni-
que
Souci des gestionnaires de conseiller et d’encourager leurs
employés à créer la documentation technique nécessaire et
2 Références
de fournir les ressources voulues pour faciliter le travail.
ISO 2382 : 1984, Traitement des données - Vocabulaire.
3) Preuve de l’intérêt et de l’appui des gestionnaires
ISO 6592 : 1985, Traitement de l’information - Principes géné- Les gestionnaires doivent assurer ce qui suit:
raux relatifs à la documentation des systèmes d’application
a) la publication d’énoncés de politique en matière de
informatisés.
documentation;
b) la définition des normes et lignes directrices en ce
ISO 9127 : 1988, Systèmes de traitement de l’information -
Documentation pour f ‘u tilisa teur et renseignements sur qui a trait à tous les aspects de la documentation techni-
que du logiciel;
l’emballage des progiciels grand public.
---------------------- Page: 5 ----------------------
ISO/CEI TR 9294 : 1990 (F)
* les spécialistes de la publication produisent la docu-
c) la publication des procédures en matière de docu-
menta tion technique; mentation destinée à l’utilisateur et ils veillent à ce que les
documents soient conformes aux politiques et aux normes
d) l’affectation des ressources suffisantes au domaine
de la documentation technique; * les spécialistes de l’assurance de la qualité et les
vérificateurs évaluent l’intégrité et la bonne qualité généra-
e) la mise en œuvre de plans de documenta tion dans
les du logiciel
cadre du processus de création des logiciels
* les programmeurs chargés de la maintenance amélio-
f) la mise en œuvre d’un processus permanent d’exa-
rent le logiciel en service et ils concoivent des améliorations
men en vue d’assurer le respect de la politique, des nor-
ou des extensions
mes, des procédures et des plans concernant la docu-
mentation.
Ces personnes ont besoin d’un moyen qui leur permette de
communiquer entre elles et qui leur assure une information qui
puisse être reconduite, diffusée et consultée au besoin.
5 Les objets de la documentation technique
du logiciel
La plupart des méthodes de création de logiciels établissent des
documents officiels dont l’objet est d’assurer la communication
Pour administrer la documentation technique en toute effica- entre les diverses activités d’un projet. Par exemple, les analy-
cité, il importe d’être au courant des différents objets de la ses présentent aux concepteurs des spécifications officielles
documentation.
faisant état des exigences à respecter et les concepteurs four-
nissent aux programmeurs des cahiers des charges officiels
On peut considérer que les six princip aux 0 Ibjets de la documen- relatifs à la conception.
tation technique sont les suivants:
5.3 Assurance de la qualité
1) la communication de renseignements à la direction
(voir 5.1) ;
Les personnes chargées de l’assurance de la qualité du logiciel
ont besoin d’une documentation sur la création et sur les pro-
2) la communication entre les différents groupes d’activité
duits pour s’acquitter de leurs fonctions.
(voir 5.2) ;
3) l’assurance de la qualité (voir 5.3);
5.4 Information et consultation
4) l’information et la consultation (voir 5.4);
Les exploitants, utilisateurs, gestionnaires et autres personnes
5) le soutien du logiciel (voir 5.5);
intéressées ont besoin de documentation technique pour être
en mesure de comprendre et d’utiliser le produit de logiciel.
6) la prestation d’un dossier historique du projet (voir 5.6).
5.5 Soutien du logiciel
5.1 CO mmunication de rensei ments à la
we
directio
Les programmeurs chargés de la maintenance ont besoin de
descriptions détaillées du logiciel pour être en mesure de détec-
Tout au long du processus de création d’un logiciel, la direction
ter et de rectifier les erreurs et d’améliorer ou de modifier le logi-
a besoin d’être tenue au courant de l’avancement des travaux,
ciel, au besoin.
des problèmes et des attentes. La présentation de rapports
d’étape qui font état de l’avancement des travaux par rapport
5.6 Dossier historique
aux échéanciers établis et qui exposent les plans concernant la
période suivante assurent les mécanismes de vérification voulus
La documentation sert également de dossier historique relative-
et la visibilité du projet.
ment au projet. Cette documentation peut également faciliter le
transfert et la conversion du logiciel dans des environnements
nouveaux.
5.2 Communication entre les différents groupes
d’activité
6 Êtablissement de la politique concernant
La plupart des projets de création de logiciel sont répartis en
diverses activités qui, dans bien des cas, sont prises en charge la documentation
par des groupes différents, nommément les suivants:
Les politiques concernant la documentation, qui sont élaborées
et appuyées par la haute direction assurent aux décisionnaires
* les spécialistes du domaine à l’étude lancent le projet
des niveaux moins élevés les directives dont ils ont besoin. Les
élaborent les exigences relatives au
* les a nalystes
politiques fournissent des directives générales, sans toutefois
système
contenir de prescriptions détaillées sur les mesures à prendre et
sur la facon de procéder.
conception du système et
* les con cepteurs élaborent la
du progra mme
En raison du rôle de premier plan que joue la documentation à
* les programmeurs créent le code du programme et tous les stades du cycle de vie du logiciel, il convient de rédiger
logiciel un énoncé officiel de politique. Toutes les personnes visées par
construisent les ensembles de
2
---------------------- Page: 6 ----------------------
lSO/CEI TR 9294 : 1990 (F)
7 Êtablissement des normes et lignes
la politique en question doivent être mises au courant de son
existence et bien la connaître. Une politique officielle, rédigée
directrices relatives à la documentation
en bonne et due forme et dûment diffusée détermine les règles
à respecter pour assurer l’efficacité de la documentation techni-
Tout orga nisme doit se doter de normes et lignes directrices
que du logiciel.
relatives à ce qui suit:
* le modèle de cycle de vie du logiciel
Toute politique concernant la documentation du logiciel doit
appuyer les principes ci-après sur lesquels se fonde l’efficacité
liens qui existent entre
* les catégories de documents et les
de la documentation :
elles
* le contenu des documents
La docu mentation est nécessa ire à tous les
1)
vie du log iciel
du cycle de
* la qualité des documents
La documentation est nécessaire dès les premières étapes * le mode de présentation des documents
de la réalisation d’un projet et elle doit être accessible et
* l’identification des documents
tenue à jour tout au long du processus de création du logi-
ciel. Une fois les travaux de développement achevés, la
Ce sont ces normes et lignes directrices qui vont déterminer la
documentation est nécessaire aux fins de l’utilisation, de la
facon de mener les travaux de documentation et fournir les cri-
maintenance, de l’amélioration, de la conversion et du
tères à utiliser pour déterminer si la documentation créée au
transfert du logiciel.
sein de l’organisme est complète, utile et appropriée.
La d oc umenta tion doit faire l’objet de m esures de
2)
II convient d’adopter les normes internationales et nationales en
tion
ws
vigueur, dans tous les cas où il est possible de le faire. En
l’absence de normes appropriées, l’organisme doit élaborer ses
L’acquisition et la tenue à jour de la documentation nécessi-
propres normes.
tent des mesures de régie et de vérification. Les gestionnai-
res et les documentalistes doivent rédiger des plans indi-
La plupart des normes et lignes directrices en vigueur fournis-
quant en détail les produits, les échéanciers, les responsabi-
sent des conseils qui s’appliquent à des situations générales.
lités, les ressources ainsi que les procédés d’assurance de la
Dans bien des cas, les gestionnaires devront faire appel à leur
qualité et d’examen relatifs à la documentation.
jugement pour adapter les conseils à caractère général à des
projets particuliers. L’application des normes prescrites par un
3) La docume doit être adaptée à ses destina-
organisme va permettre aux gestionnaires de projet de détermi-
taires
ner ce qui suit:
La documentation est susceptible d’être utilisée par des ges-
* les catégories de documents nécessaires
tionnaires, des analystes, des professionnels ne possédant
aucune spécialisation en informatique, des programmeurs
* la quantité de documents à prévoir
chargés de la maintenance, des commis aux écritures et
* le contenu des documents
autres. Selon les fonctions remplies par les intéressés, les
besoins ne sont pas les mêmes pour ce qui est du degré de
* la qualité à assurer
précision et du mode de présentation des documents. II y
aurait lieu de confier à un documentaliste la tâche de conce-
* la date à laquelle les documents doivent être produits
voir différentes catégories de documentation en fonction
* la facon dont les documents doivent être stockés, tenus à
des différe
...
ISOICEI
RAPPORT
TECHNIQUE TR 9294
Première édition
1990-11-15
Technologies de l’information - Lignes
directrices pour la gestion de la documentation
technique du logiciel
Guidelines for the management of software
Information technology -
documentation
Numéro de référence
ISOKEI TR 9294 : 1990 (FI
---------------------- Page: 1 ----------------------
ISO/CEI TR 9294 : 1990 (F)
Sommaire page
iii
Avant-propos. .
............................................................ iv
Introduction
................................................ 1
1 Domaine d’application
.......................................................... 1
2 Références
3 Définitions . 1
................................................
4 Rôle des gestionnaires 1
....................... 2
5 Les objet de la documentation technique du logiciel
..................... 2
5.1 Communication de renseignements à la direction
................
5.2 Communication entre les différents groupes d’activité. 2
........................................... 2
5.3 Assurance de la qualité
....................................... 2
5.4 Information et consultation
...............................................
5.5 Soutien du logiciel 2
............................................... 2
5.6 Dossier historique
................. 2
6 Etablissement de la politique concernant la documentation
7 Etablissement des normes et lignes directrices relatives à la documentation . 3
........................ 3
7.1 Choix d’un modèle de cycle de vie du logiciel
.. 4
7.2 Définition des catégories de documents et du contenu des documents.
7.3 Définition de la qualité des documents . 5
..................
7.4 Définition du mode de présentation des documents. 5
............
7.5 Définition d’un mécanisme d’identification des documents. 5
................. 6
8 Établissement des procédures relatives à la documentation
........................... 6
9 Affectation des ressources à la documentation
............................................
9.1 Ressources humaines 6
.................................................... 6
9.2 Installations
...........................................
9.3 Ressources financières 6
......................................
10 Planification de la documentation. 6
Annexe A Mesures à prendre pour assurer la gestion de la documentation
technique du logiciel
A.1 Mesures relatives aux lignes de conduite. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
A.2 Mesures à prendre dans le domaine des normes . . . . . . . . . . . . . . . . . . . . . . . . .
8
A.3 Mesures à prendre dans le domaine des procédures . . . . . . . . . . . . . . . . . . . . . . 8
A.4 Mesures à prendre dans le domaine de la gestion du projet . . . . . . . . . . . . . . . . 8
@ ISOKEI 1990
Droits de reproduction réservés. Aucune partie de cette publication ne peut être reproduite ni
utilisée sous quelque forme que ce soit et par aucun procédé, électronique ou mécanique,
y compris la photocopie et les microfilms, sans l’accord écrit de l’éditeur.
ISOKEI Copyright office l Case postale 56 l CH-1211 Genève 20 l Suisse
Imprimé en Suisse
ii
---------------------- Page: 2 ----------------------
ISO/CEI TR 9294 : 1990 (F)
Avant-propos
L’ISO (Organisation internationale de normalisation) et la CEI (Commission électro-
technique internationale) forment le système spécialisé de normalisation mondiale. Les
organismes nationaux membres de I’ISO ou de la CEI participent au développement de
Normes internationales par l’intermédiaire des comités techniques créés par I’organisa-
tion concernée afin de s’occuper des différents domaines particuliers de l’activité tech-
nique. Les comités techniques de I’ISO et de la CEI collaborent dans des domaines
d’intérêt commun. D’autres organisations internationales, gouvernementales ou non
gouvernementales, en liaison avec I’ISO et la CEI participent également aux travaux.
Dans le domaine des technologies de l’information, I’ISO et la CEI ont créé un comité
technique mixte, I’ISOKEI JTC 1.
La tâche principale des comités techniques est d’élaborer les Normes internationales,
mais, exceptionnellement, un comité technique peut proposer la publication d’un
rapport technique de l’un des types suivants:
-
1, lorsque, en dépit de maints efforts, l’accord requis ne peut être réalisé
type
en faveur de la publication d’ ‘une Norme internationale;
-
type 2, lorsque le sujet en question est encore en cours de développement
technique ou lorsque, pour toute autre raison, la possibilité d’un accord pour la
publication d’une Norme internationale peut être envisagée pour l’avenir mais pas
dans l’immédiat;
-
type 3, lorsqu’un comité technique a réuni des données de nature différente de
celles qui sont normalement publiées comme Normes internationales (ceci pouvant
comprendre des informations sur l’état de la technique, par exemple).
Les rapports techniques des types 1 et 2 font l’objet d’un nouvel examen trois ans au plus
tard après leur publication afin de décider éventuellement de leur transformation en Nor-
mes internationales. Les rapports techniques du type 3 ne doivent pas nécessairement
être révisés avant que les données fournies ne soient plus jugées valables ou utiles.
L’ISOKEI TR 9294, rapport technique du type 3, a été élaboré par le comité technique
mixte ISOKEI JTC 1, Technologies de l’information.
. . .
III
---------------------- Page: 3 ----------------------
ISO/CEI TR 9294 : 1990 (F)
Introduction
La documentation technique est nécessaire à tous les stades du cycle de vie du logiciel.
En conséquence, l’élaboration et la tenue à jour de la documentation technique consti-
tuent des fonctions indispensables et permanentes à assurer à partir du moment où le
logiciel est créé jusqu’à sa mise au rancart. L’élaboration de la documentation techni-
que commence au moment du lancement d’un projet de logiciel et elle se poursuit au
fur et à mesure de la conception, du développement, de la mise à l’essai, de I’installa-
tion, de l’utilisation, de la modification et de l’amélioration du logiciel. Le traitement de
la documentation technique ne peut être considéré terminé que lorsque le logiciel par-
vient à la fin de sa vie utile.
La documentation technique est indispensable au succès de tout projet de création de
logiciel et la production de la documentation technique exige que l’on y engage du
temps, des efforts et des ressources financières. II est du devoir des gestionnaires de
veiller à investir ces ressources en toute efficacité, en tenant compte de l’importance
que revêt la documentation technique pour la qualité et la réussite du produit de
logiciel.
iV
---------------------- Page: 4 ----------------------
ISO/CEI TR 9294 : 1990 (F)
RAPPORT TECHNIQUE
Technologies de l’information - Lignes directrices pour la
gestion de la documentation technique du logiciel
3 Définitions
1 Domaine d’application
Pour les besoins du présent Rapport technique, les définitions
Le présent Rapport technique offre des conseils sur la gestion
suivantes s’appliquent.
de la documentation technique du logiciel aux gestionnaires
chargés de la création de produits logiciels ou de produits utili-
3.1 document: Unité d’information possédant son identité
sant les logiciels. Ces conseils visent à faciliter aux gestionnai-
propre et lisible par l’homme, par exemple un rapport, un cahier
res la tâche de veiller à l’élaboration d’une documentation tech-
des charges, un guide ou un livre.
nique efficace au sein de leur organisation.
3.2 documentation: Collection constituée d’un ou de plu-
II traite des politiques, des normes, des procédures, des
sieurs documents connexes.
ressources et des plans qui méritent de retenir l’attention des
gestionnaires désireux de gérer en toute efficacité la documen-
tation technique du logiciel.
3.3 produit de logiciel: Résultat du processus de création
de logiciels, c’est-à-dire logiciel lancé pour fin d’utilisation.
Les directives données dans le présent Rapport technique sont
censées être applicables à toutes les catégories de logiciel, à
partir du programme le plus simple jusqu’au progiciel le plus
4 Rôle des gestionnaires
complexe. On y traite de toutes les catégories de documenta-
Les gestionnaires amènent leur organisme à s’engager dans un
tion technique du logiciel, par rapport à tous les stades du cycle
de vie du logiciel visé. travail de documentation qu’ils appuient dans les politiques, les
normes, les procédures, les affectations de ressources et les
plans qu’ils établissent.
Les principes qui sous-tendent la gestion de la documentation
technique du logiciel sont les mêmes, peu importe l’envergure
Pour évaluer dans quelle mesure les gestionnaires s’acquittent
du projet. En ce qui a trait aux petits projets, il se peut qu’une
du rôle qui leur revient sous ce rapport, on peut se fonder sur
grande partie des détails énoncés dans le présent Rapport tech-
les trois éléments suivants :
nique ne soient pas applicables, mais les principes demeurent
les mêmes. Les gestionnaires pourront adapter à leurs besoins
1) Intérêt des gestionnaires à l’égard de la documen-
particuliers les recommandations qui y sont faites.
tation
Les gestionnaires doivent reconnaître que la documentation
À noter que les directives données dans le présent Rapport
technique est importante et qu’elle doit être planifiée, rédi-
technique sont concues dans la perspective de la gestion de la
gée, examinée, approuvée, produite, distribuée et tenue à
documentation technique. II n’y est pas donné de conseils
jour.
détaillés sur le contenu ni sur le mode de présentation des
documents concernant les logiciels.
2) Appui des gestionnaires à l’intérêt manifesté par
leurs employés à l’égard de la documentation techni-
que
Souci des gestionnaires de conseiller et d’encourager leurs
employés à créer la documentation technique nécessaire et
2 Références
de fournir les ressources voulues pour faciliter le travail.
ISO 2382 : 1984, Traitement des données - Vocabulaire.
3) Preuve de l’intérêt et de l’appui des gestionnaires
ISO 6592 : 1985, Traitement de l’information - Principes géné- Les gestionnaires doivent assurer ce qui suit:
raux relatifs à la documentation des systèmes d’application
a) la publication d’énoncés de politique en matière de
informatisés.
documentation;
b) la définition des normes et lignes directrices en ce
ISO 9127 : 1988, Systèmes de traitement de l’information -
Documentation pour f ‘u tilisa teur et renseignements sur qui a trait à tous les aspects de la documentation techni-
que du logiciel;
l’emballage des progiciels grand public.
---------------------- Page: 5 ----------------------
ISO/CEI TR 9294 : 1990 (F)
* les spécialistes de la publication produisent la docu-
c) la publication des procédures en matière de docu-
menta tion technique; mentation destinée à l’utilisateur et ils veillent à ce que les
documents soient conformes aux politiques et aux normes
d) l’affectation des ressources suffisantes au domaine
de la documentation technique; * les spécialistes de l’assurance de la qualité et les
vérificateurs évaluent l’intégrité et la bonne qualité généra-
e) la mise en œuvre de plans de documenta tion dans
les du logiciel
cadre du processus de création des logiciels
* les programmeurs chargés de la maintenance amélio-
f) la mise en œuvre d’un processus permanent d’exa-
rent le logiciel en service et ils concoivent des améliorations
men en vue d’assurer le respect de la politique, des nor-
ou des extensions
mes, des procédures et des plans concernant la docu-
mentation.
Ces personnes ont besoin d’un moyen qui leur permette de
communiquer entre elles et qui leur assure une information qui
puisse être reconduite, diffusée et consultée au besoin.
5 Les objets de la documentation technique
du logiciel
La plupart des méthodes de création de logiciels établissent des
documents officiels dont l’objet est d’assurer la communication
Pour administrer la documentation technique en toute effica- entre les diverses activités d’un projet. Par exemple, les analy-
cité, il importe d’être au courant des différents objets de la ses présentent aux concepteurs des spécifications officielles
documentation.
faisant état des exigences à respecter et les concepteurs four-
nissent aux programmeurs des cahiers des charges officiels
On peut considérer que les six princip aux 0 Ibjets de la documen- relatifs à la conception.
tation technique sont les suivants:
5.3 Assurance de la qualité
1) la communication de renseignements à la direction
(voir 5.1) ;
Les personnes chargées de l’assurance de la qualité du logiciel
ont besoin d’une documentation sur la création et sur les pro-
2) la communication entre les différents groupes d’activité
duits pour s’acquitter de leurs fonctions.
(voir 5.2) ;
3) l’assurance de la qualité (voir 5.3);
5.4 Information et consultation
4) l’information et la consultation (voir 5.4);
Les exploitants, utilisateurs, gestionnaires et autres personnes
5) le soutien du logiciel (voir 5.5);
intéressées ont besoin de documentation technique pour être
en mesure de comprendre et d’utiliser le produit de logiciel.
6) la prestation d’un dossier historique du projet (voir 5.6).
5.5 Soutien du logiciel
5.1 CO mmunication de rensei ments à la
we
directio
Les programmeurs chargés de la maintenance ont besoin de
descriptions détaillées du logiciel pour être en mesure de détec-
Tout au long du processus de création d’un logiciel, la direction
ter et de rectifier les erreurs et d’améliorer ou de modifier le logi-
a besoin d’être tenue au courant de l’avancement des travaux,
ciel, au besoin.
des problèmes et des attentes. La présentation de rapports
d’étape qui font état de l’avancement des travaux par rapport
5.6 Dossier historique
aux échéanciers établis et qui exposent les plans concernant la
période suivante assurent les mécanismes de vérification voulus
La documentation sert également de dossier historique relative-
et la visibilité du projet.
ment au projet. Cette documentation peut également faciliter le
transfert et la conversion du logiciel dans des environnements
nouveaux.
5.2 Communication entre les différents groupes
d’activité
6 Êtablissement de la politique concernant
La plupart des projets de création de logiciel sont répartis en
diverses activités qui, dans bien des cas, sont prises en charge la documentation
par des groupes différents, nommément les suivants:
Les politiques concernant la documentation, qui sont élaborées
et appuyées par la haute direction assurent aux décisionnaires
* les spécialistes du domaine à l’étude lancent le projet
des niveaux moins élevés les directives dont ils ont besoin. Les
élaborent les exigences relatives au
* les a nalystes
politiques fournissent des directives générales, sans toutefois
système
contenir de prescriptions détaillées sur les mesures à prendre et
sur la facon de procéder.
conception du système et
* les con cepteurs élaborent la
du progra mme
En raison du rôle de premier plan que joue la documentation à
* les programmeurs créent le code du programme et tous les stades du cycle de vie du logiciel, il convient de rédiger
logiciel un énoncé officiel de politique. Toutes les personnes visées par
construisent les ensembles de
2
---------------------- Page: 6 ----------------------
lSO/CEI TR 9294 : 1990 (F)
7 Êtablissement des normes et lignes
la politique en question doivent être mises au courant de son
existence et bien la connaître. Une politique officielle, rédigée
directrices relatives à la documentation
en bonne et due forme et dûment diffusée détermine les règles
à respecter pour assurer l’efficacité de la documentation techni-
Tout orga nisme doit se doter de normes et lignes directrices
que du logiciel.
relatives à ce qui suit:
* le modèle de cycle de vie du logiciel
Toute politique concernant la documentation du logiciel doit
appuyer les principes ci-après sur lesquels se fonde l’efficacité
liens qui existent entre
* les catégories de documents et les
de la documentation :
elles
* le contenu des documents
La docu mentation est nécessa ire à tous les
1)
vie du log iciel
du cycle de
* la qualité des documents
La documentation est nécessaire dès les premières étapes * le mode de présentation des documents
de la réalisation d’un projet et elle doit être accessible et
* l’identification des documents
tenue à jour tout au long du processus de création du logi-
ciel. Une fois les travaux de développement achevés, la
Ce sont ces normes et lignes directrices qui vont déterminer la
documentation est nécessaire aux fins de l’utilisation, de la
facon de mener les travaux de documentation et fournir les cri-
maintenance, de l’amélioration, de la conversion et du
tères à utiliser pour déterminer si la documentation créée au
transfert du logiciel.
sein de l’organisme est complète, utile et appropriée.
La d oc umenta tion doit faire l’objet de m esures de
2)
II convient d’adopter les normes internationales et nationales en
tion
ws
vigueur, dans tous les cas où il est possible de le faire. En
l’absence de normes appropriées, l’organisme doit élaborer ses
L’acquisition et la tenue à jour de la documentation nécessi-
propres normes.
tent des mesures de régie et de vérification. Les gestionnai-
res et les documentalistes doivent rédiger des plans indi-
La plupart des normes et lignes directrices en vigueur fournis-
quant en détail les produits, les échéanciers, les responsabi-
sent des conseils qui s’appliquent à des situations générales.
lités, les ressources ainsi que les procédés d’assurance de la
Dans bien des cas, les gestionnaires devront faire appel à leur
qualité et d’examen relatifs à la documentation.
jugement pour adapter les conseils à caractère général à des
projets particuliers. L’application des normes prescrites par un
3) La docume doit être adaptée à ses destina-
organisme va permettre aux gestionnaires de projet de détermi-
taires
ner ce qui suit:
La documentation est susceptible d’être utilisée par des ges-
* les catégories de documents nécessaires
tionnaires, des analystes, des professionnels ne possédant
aucune spécialisation en informatique, des programmeurs
* la quantité de documents à prévoir
chargés de la maintenance, des commis aux écritures et
* le contenu des documents
autres. Selon les fonctions remplies par les intéressés, les
besoins ne sont pas les mêmes pour ce qui est du degré de
* la qualité à assurer
précision et du mode de présentation des documents. II y
aurait lieu de confier à un documentaliste la tâche de conce-
* la date à laquelle les documents doivent être produits
voir différentes catégories de documentation en fonction
* la facon dont les documents doivent être stockés, tenus à
des différe
...
Questions, Comments and Discussion
Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.