Dans le chapitre précédent, nous avons vu comment écrire de la documentation en vous adaptant aux besoins des parties prenantes du projet.
Dans ce chapitre, nous allons voir quelques bonnes pratiques et des exemples concrets pour représenter votre documentation.
Quelques conseils et exemples
Commencez à documenter avant d'entamer le développement
Imaginez que vous êtes un architecte qui va concevoir et construire une maison pour une famille qui y vivra. Cette famille est votre client. Vous les avez rencontrés et vous vous demandez : ont-ils besoin de trois ou de quatre chambres ? Leur faut-il un garage ? Quelle doit être la taille de la cuisine ?
Vous élaborez le cahier des charges dans votre tête. Vous avez une idée, mais elle n'est pas encore tout à fait claire. Posez l'idée sur le papier ! Vous devrez expliquer votre vision de cette maison à beaucoup de gens : vos partenaires, les maçons, les électriciens, les plombiers. Tous ceux qui travailleront avec vous sur ce projet. Vous avez besoin d'une explication homogène et cohérente du type de maison que vous devez construire. Cette explication doit se traduire dans un document.
Alors, que faut-il faire ? Documenter ou ne pas documenter ?
La décision clé, c'est de trouver le bon équilibre !
Scott Ambler, un ingénieur logiciel, consultant et écrivain canadien, a dit à propos des projets agiles : « Produisez uniquement une documentation que vous pouvez gérer avec précision ». Il a ajouté : « L'idéal, c'est même de trouver quelque chose de "tout juste suffisant" » (just barely good enough, en anglais).
C'est cette philosophie que décrit le schéma suivant : l'axe des X représente l'effort investi dans la documentation et l'axe des Y la valeur obtenue. Il existe un point d'effort optimal. Au-delà de ce point, la valeur de la documentation diminue :
Le choix du style le plus adapté à votre projet dépend de votre contexte spécifique :
Qui vous êtes.
Pour qui vous écrivez.
À propos de quoi vous écrivez.
Principes directeurs pour la documentation
Voici quelques grands principes directeurs à prendre en compte pour créer la documentation :
Optimisez l'investissement du lecteur : vos lecteurs vont investir du temps dans la lecture de votre document. Cela en vaut-il la peine ? Le bénéfice est-il supérieur au coût ? Posez-vous la question avant de commencer.
Documentez les informations qui risquent le moins de changer : séparez les concepts éphémères des concepts durables. Un document contenant des informations qui se modifient rapidement devient obsolète et par conséquent difficile à gérer au fil du temps. Décrivez « ce qu'il est bon de savoir » : si je devais retenir trois concepts de votre document, desquels s'agirait-il ?
Organisez votre contenu de façon logique et progressive : allez du général au particulier, zoomez sur quelques schémas, expliquez pas à pas. Le contenu doit être agencé de façon à traiter d'abord des concepts préalables.
Traitez les concepts dans leur intégralité ou pas du tout : évitez les explications incomplètes. Si un concept repose sur les éléments A, B et C, vous devez d'abord expliquer ces éléments A, B et C, puis expliquer le concept.
Intégrez des exemples dans le contenu : les exemples clarifient les concepts abstraits et les rendent faciles à comprendre.
Principes particuliers et exemples
Voici quelques principes directeurs spécifiques à prendre en compte pour créer une documentation, chacun étant accompagné d'un exemple :
Évitez les schémas complexes
Réduisez le nombre de cases, d'icônes et de flèches pour faire des schémas simples, immédiatement compréhensibles.
Prenons un exemple de schéma complexe et difficile à comprendre. Nous avons vu ces deux schémas au chapitre 1 :
Que se passe-t-il si nous continuons à ajouter des détails ?
Mauvaise idée... ce schéma devient difficile à comprendre. Il est préférable de zoomer sur les détails dans des schémas distincts :
Expliquez les données des tableaux
Si un tableau est présenté, expliquez les rangées et les colonnes : lorsque je vois un tableau, j'ai besoin de savoir ce que représentent les colonnes et les rangées. Décrivez-les donc d'abord avant d'expliquer les cellules du tableau. C'est une erreur que l'on retrouve couramment dans les présentations professionnelles.
Exemple :
Type de paiement | Notre commission | Commission de l'opérateur |
Espèces | 0 % | 0 % |
Chèque | 0 % | 0.5 % |
Virement bancaire | 0 % | 1.2 % |
Carte de crédit | 0 % | 3.5 % |
PayPal | 1.5 % | 4.5 % |
Vous devez expliquer ce que représentent les colonnes et les rangées : « Ce tableau décrit les différents types de paiement que la société accepte dans le cadre de ses transactions courantes, ainsi que la commission que le client paie pour chaque type.
Les rangées représentent les différents types de paiement. Les colonnes décrivent la commission perçue par notre société et celle perçue par les opérateurs de paiement. »
Expliquez les axes des graphiques
Si un graphique XY est présenté, expliquez l'axe des X et celui des Y : comme précédemment. Cette erreur est également courante dans les présentations professionnelles.
Vous devez expliquer ce que représentent l'axe des X et l'axe des Y : « Ce graphique d'avancement montre la durée du projet en jours sur l'axe des X, et les tâches restant à effectuer sur l'axe des Y. »
Documentation-Driven Design
Si votre logiciel n'a pas encore été créé, vous pouvez élaborer sa documentation pour faciliter le processus de conception. On parle alors de "Documentation-Driven Design", ou "conception basée sur la documentation".
Si vous concevez votre logiciel en vous appuyant sur la documentation, vous pouvez facilement recueillir les réactions et modifier la conception avant même de commencer le développement.
Utilisez des tableaux pour les développeurs
Voici un exemple de tableau décrivant des types de remise en fonction des types de clients :
Type de client | Période de remise | Remise |
Commercial | Trois 1res années | 12 % |
Résidentiel | Cinq 1res années | 8 % |
Administration | Perpétuelle | 10 % |
Défense | Perpétuelle | 10 % |
Santé | Cinq 1res années | 16 % |
Ce tableau sera utilisé par un grand nombre de parties prenantes, telles que les développeurs, les architectes système, les concepteurs de logiciels et les administrateurs de bases de données.
Voici un exemple de code qui l'utilise :
//GetCustomerData.txt
/*
La fonction GetCustomerDiscount obtient la remise client pour tous les produits
*/
fonction GetCustomerDiscount(CustomerID)
{
GetCustomerData(CustomerID);
rval = 0;
switch(CustomerID.type)
{
case 1:
// Commercial
rval = 12;
case 2:
// Résidentiel
rval = 8;
case 3:
// Administration
rval = 10;
case 4:
// Défense
rval = 10;
case 5:
// Santé
rval = 16;
}
return rval;
}
En résumé
Commencez à documenter avant d'entamer le développement : un document d'architecture logicielle est une carte du logiciel, et vous avez besoin d'une carte !
Documentation « tout juste suffisante » : ni trop, ni trop peu.
Conception basée sur la documentation : modifier la documentation reste bon marché, modifier le code coûte cher.
Grands principes directeurs pour la documentation :
Optimisez l'investissement du lecteur.
Documentez les informations qui risquent le moins de changer.
Décrivez « ce qu'il est bon de savoir ».
Organisez votre contenu de façon logique et progressive.
Traitez les concepts dans leur intégralité ou pas du tout.
Intégrez des exemples dans le contenu.
Évitez les schémas complexes.
Si un tableau est présenté, expliquez les rangées et les colonnes.
Si un graphique XY est présenté, expliquez l'axe des X et celui des Y.
Dans le prochain chapitre, nous verrons quelques outils standard, comme l'UML et les User Stories, pour documenter votre projet et son architecture.
