Documentation de logiciel
La documentation est complémentaire au logiciel. Elle permet de savoir à quoi sert le produit, comment l'utiliser et le maintenir.
Importances d'une documentation de qualités
- Permettre à un nouveau collaborateur de rentrer dans le projet,
- Décrire une convention d'écriture pour tout le projet,
- Informer le client en détail des fonctionnalités technique du produit,
- Avoir des spécifications techniques détaillés,
- Facilité la maintenance du produit,
- Avoir une rigueur dans le contexte de travail,
- …
Que doit on mettre dans une documentation technique?
Quelques idées d'usage, dans l'idéal quand on a le temps!
Quatre types de documentation:
- Documentation utilisateur;
- Documentation pour le développeur;
- Documentation pour l'administrateur;
- Documentation client.
Dans un environnement de travail collaboratif, l'usage d'un WIKI est une bonne option:
- Tout un chacun, peut y avoir accès, les clients, testeurs, et administrateur;
- Il y a une gestion des conflits en cas de modification simultanée de la même page;
- Il y a possibilité d'édition rapide, on peut très rapidement partager les modifications et commentaires sur le développement.
Utilisation d'une bibliothèque de documentation (Plone) qui permet de suivre la documentation :
- État du document;
- Différentes versions;
- …
Documentation pour le développeur
- Les spécification détaillées;
- Description de l'architecture:
- Les schémas UML;
- Explications des choix et des classes;
- Idées d'extensions possibles.
- Avancement et planning
- Fonctionnalités en cours dans le cycle;
- Action à réaliser;
- État des bugs trouvés des versions précédentes.
- Historique des développements(traçage)
- Mettre des commentaires dans le code sources.
Documentation pour l'utilisateur
- Pour la prise en main, indiquer un cas simple de fonctionnement.
- Expliciter un scénario détaillé, pour les grandes fonctionnalités utiles.
- Créer une F.A.Q pour les aider, en cas de difficulté.
Documentation pour l'administrateur
- Comment régénérer l'application à partir de CVS, ou SVN;
- Comment configurer les dépendances, par exemple les datas sources;
- Expliquer les réglages spécifiques, à la configuration;
- Comment déployer l'application.
Documentation pour le client
- Spécification technique;
- Spécification fonctionnelles;
Gestion de la documentation
Cycle de vie des documents
Qualification d’un document projet
La Qualification d’un document désigne sa portée et son état.
Porté
- Privé
- consultable
- Livrable
État
La version est en cours de rédaction | EN COURS |
---|---|
Le document a été revu en interne | REVU |
Le document a été approuvé par le client | APPROUVÉ |
Le document ne doit plus être utilisé ni diffusé | OBSOLÈTE |
Version
Un document approuvé a fortiori diffusé ne doit jamais être modifié dans sa version courante. Pour le modifier on doit créer une nouvelle version du document.
La version d'un document (XX.Y) est composée
- d'un indice d'édition XX sur 2 chiffres.
- d'un indice de révision sur Y sur 1 chiffre.
L'indice d'édition XX augmente par pas de 1 (01, 02, 03, …) pour identifier les versions successives approuvées d’un document. Par définition, la modification même mineure d’un document entraîne un changement de son numéro de révision.
L'indice de révision Y augmente par pas de 1 (0, 1, 2, 3, …) pour identifier les paliers de modification d’une évolution en cours d’élaboration.
Une version 00.0 correspond à un document identifié et réservé dans le dictionnaire mais non encore créé.
Évolution de l’édition et de la révision
Création d’un document
Version | Actions |
---|---|
00.0 | Réservation de la référence |
00.1 | Création et première saisie du document |
00.2 | 1ère modification |
00.3 | 2ieme modification |
01.0 | Revue du document |
Modification du document
Version | Actions |
---|---|
01.0 | version de référence |
01.1 | 1ère modification |
01.2 | 2ieme modification |
02.0 | Revue du document |
Préciser la justification de la modification : référence aux fiches de lectures, demande du client, prise en compte remarques client, évolutions, etc.
Le plan
L'introduction
Introduction générale du document
- Introduire le document, en précisant les objectifs et les besoins.
- Détailler le but et la porté du document,
- Expliquer l'organisation et la structure du document:
- le chapitre … décrit …
- la chapitre … fournit une vue global sur …
- Préciser les documents de référence pour ce document.
- Donner les définitions des termes et abréviation.