On documente, quoi, quand et comment ?

On documente, quoi, quand et comment ?

Je ne compte plus le nombre de fois que j’ai attendu l’horreur suivante : « On est en agile, donc on ne fait pas de documentation ! »

Mais, pourtant c’est justement en agile qu’il faut bien documenter. C’est un oxymoron, tant en agile qu’autrement de dire qu’on ne fait pas de documentation.

Mais, ce n’est pas tout de dire qu’il faut documenter. Comme dans toutes choses il faut savoir comment, quand et surtout quoi !

D'abord, revenons à la base, c’est quoi la fin ultime d’une bonne documentation.

Généralement, une bonne documentation a deux fins. La première, c’est de créer un terrain d’entente, un langage commun entre les parties. On pourrait dire une forme de contrat sur qu’est ce qu’on va faire.

La deuxième fin qu’on oublie souvent dans la documentation, c’est la maintenance de l’application ou du logiciel qu’on développe. Plusieurs statistiques démontrées que l’effort (le temps consacré à cet exercice) de la maintenance sera la phase la plus importante durant sa vie utile. Il y aura plus d’heures consacrées à la maintenance qu’au développement propre.

Maintenant qu’on sait à quoi va servir la documentation. Donc, on peut se pencher sur le quoi !

Prenons un petit exemple. Une petite application qui permet de saisir la fiche d’une employée. L’information nominative de l’employer. (Nom, prénom, coordonnées, etc.)

Je ne suis pas sur qu’il est intéressant de document dans un long document, l’interface graphique en décrivant chacun des champs, une image de l'interface pourrait-être suffisant.

Mais, à l’inverse, s’il y a une règle de validation de l’information entre elle. A titre d’exemple, une règle qui oblige la confirmation de l’information saisir par un directeur. Là c’est important de la documenter.

Bien sûr, en plus de documenter la partie « fonctionnelle » de l’application. Il faut aussi documenter le code, la base de données.

C’est intéressant et surtout nécessaire, de produire de la documentation. Mais, cela ne veut pas dire pour autant de tout décrire ou d’écrire dans un beau document produit avec Microsoft Word. On est des informaticiens pas des auteurs de romans savons.

On peut utiliser Word, mais ce n’est pas le seul outil à notre disposition. Il en existe plein d’autres.

Il faut là aussi être « agile » dans la production de la documentation. Il existe plusieurs outils qui sont capables de produire une base de documentation organique à partir des commentaires dans le code (oui, oui, il faut inscrire des commentaires. Rappelez-vous toujours qu’il y aura de la maintenance sur votre travail.)

Les différents diagrammes UML bien produit peuvent aussi servir à cette base de documentation. Et il n’est pas nécessaire, de « TRADUIRE » en français un « cas d’utilisation » à 4 bulles (Création, Modification, Suppression, Recherche (CRUD)) d’un employé. Ne devons pas stupide à l’inverse.

Une présentation PowerPoint pourrait aussi servir pour présenter un scénario (défilement des écrans) de navigations ou encore un arbre hiérarchique ou décisionnel. On dit bien qu’une image vaut mille mots. Rappelez-vous-en quand vous faites de la documentation.

Et pour répondre, à la dernière question posée. Après tout, elle est aussi importante que les autres. Le fameux « QUAND ». Je me souviens, à l'université on la faisait toujours en dernier. Juste avant de partir pour aller porter notre travail au professeur.

Beaucoup trop de gens, moi, aussi j’en étais un de ceux-là. Produise la documentation en catastrophe à la fin du projet et du bien livrable. Mais, est-ce que vous êtes relus les commentaires ou la documentation que vous aviez produite en catastrophe à la fin du bien livrable. Versus celle que vous aviez prise le temps de faire en produisant le code. N’oubliez pas, la mémoire est une faculté qui oublie. C’est beaucoup plus facile de documenter un algorithme quand elle fraiche à la mémoire.

Le constat est facile à faire. La documentation produite en catastrophe reste toujours une documentation produite en catastrophe. Et celle que vous avez pris le temps de le faire, est souvent de qualité bien supérieure.

Donc, la réponse est toute simple. La documentation n’est pas une punition, ce n’est pas un passage obligé. Mais, une chose aussi importante que le code en lui-même. Ce qui veut dire, on n’a pas besoin de répondre quand il faut produire la documentation.

Car, elle doit être le faire tout le temps. Une règle forte simple qu’on m’a apprise et que je transmets encore aujourd’hui. Si tu regardes une ligne de code, une interface, un procédé et que ça prend plus de temps à le comprendre que ça t’a pris à le lire. Documente-les.

Et surtout, ce n’est pas le temps d’écrire des romans, et encore moins des encyclopédies. Écrire simplement ce qui est nécessaire à la compréhension, de ce que tu dois documenter. En utilisant des points de formes, un tableau synthèse au besoin.

En résumé, on document ce qui est important pour la compréhension du travail qui est à faire et de sa maintenance. Quand, tout le temps bien sûr.

Et le comment, en se servant de l’outil qui rendra le mieux l’information qu’on doit transmettre. Laisser les figures de style shakespeariennes à Shakespeare lui-même !

Allez documenter ..!