veillelogiciels:gestiondocumentations

Documentation de logiciel

La documentation est complémentaire au logiciel. Elle permet de savoir à quoi sert le produit, comment l'utiliser et le maintenir.

  • 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,

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;
  • 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.
  • 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é.
  • 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.
  • Spécification technique;
  • Spécification fonctionnelles;

Gestion de la documentation

La Qualification d’un document désigne sa portée et son état.

  • Privé
  • consultable
  • Livrable
La version est en cours de rédactionEN COURS
Le document a été revu en interneREVU
Le document a été approuvé par le clientAPPROUVÉ
Le document ne doit plus être utilisé ni diffuséOBSOLÈTE

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éé.

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

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.
  • veillelogiciels/gestiondocumentations.txt
  • Dernière modification: 2018/10/13 14:59
  • (modification externe)