11.9.6 : Documentation
La documentation est une partie critique dans de trop nombreux projets, alors qu'une documentation efficace est la seule garantie pour que les utilisateurs apprécient et recommandent l'utilisation de tel ou tel programme.
Dans l'idéal, une documentation est en fait constituée d'au moins deux documentations :
- une documentation pour les utilisateurs
- une documentation pour les développeurs
La documentation des utilisateurs est la plus complexe à produire, car elle requiert une vision d'assez haut niveau des fonctionnalités fournies, et est bien plus efficace et appréciée si elle est composée de cours et d'exemples (qui peuvent être inspirés de certains tests unitaires). Il est tout de même préférable d'écrire ces cours ou ces exemples une fois que l'on est sûr que les fonctionnalités présentées ne seront pas supprimées.
La documentation des développeurs est la plus simple à réaliser et peut être utilisée comme un outil de développement à part entière plutôt que le dernier livrable d'un produit fini.
En effet, l'écriture continue de cette documentation à l'ajout de chaque fonction permet d'une part d'expliquer clairement l'objectif de cette fonction (si l'objectif n'est pas clair, il faut revoir la conception ou découper la fonction en plusieurs fonctions aux objectifs simples et clairs, cela permet d'éprouver la conception du programme avant même de commencer à écrire du code, ce qui est un gain de temps en soi).
Dans le cas où l'on a pas le temps d'écrire la fonction, avoir sa documentation permet de se rappeler plus facilement de ces objectifs et cela évite de changer d'avis en plein développement (ce qui provoque des bogues qui peuvent être extrêmement difficiles à trouver et à corriger).
Enfin cette documentation peut être écrite en quelques mots avec la description des paramètres ainsi que de la valeur retournée. Et bien que cela ne prenne que quelques secondes pendant son développement (car les idées sont fraîches) cela prendra de plusieurs minutes à plusieurs jours si cette documentation est écrite des mois ou des années plus tard).
Il est indispensable d'écrire cette documentation pendant la phase de développement et non après, car cela va gagner un temps conséquent en fin de projet.
La documentation des développeurs peut être mise en forme par des programmes comme Doxygen[103]Doxygen - Generate documentation from source code, Dimitri van Heesch, Sphynx[104]Sphynx - Python documentation generator, Georg Brandl grâce à l'utilisation de commentaires spéciaux. Cela simplifie d'autant son écriture.