Quelques bonnes pratiques qui simplifient la maintenance de la documentation technique d'un projet

1   Introduction

Au quotidien, j'essaie autant que possible d'être un développeur agile. Agile dans ma façon de "coder", agile dans ma façon de concevoir la documentation technique de mes projets.

Dans cet article, je vais dresser une liste de quelques bonnes pratiques qui permettent de réaliser et de maintenir efficacement la documentation technique d'un projet. J'essaie personnellement de les suivre dans mes projets bien que cela ne soit pas toujours le cas... et c'est mal :).
L'origine de la plupart de ces bonnes pratiques proviennent de lectures diverses ou de l'observation de projets existants.
Quelques-unes d'entre elles viennent de réflexions personnelles.

2   Problématique

En génie logiciel, la mise à jour des documentations techniques est un problème récurrent.
Il est très difficile d'avoir assez de rigueur pour tenir à jour les documentations tout au long de la vie d'un projet.

Au cours de la vie d'un projet, de nombreux événements viennent perturber les plans initiaux des développeurs : cahier des charges incomplets ou erronés, évolution du besoin initial, erreurs de conceptions ou d'analyse... il faut ajouter à cela le refactoring nécessaire à l'amélioration constante de la qualité et la consistance du code source.

Ces événements ont des conséquences directes sur le code source : modification des API, création de nouvelles classes, suppression d'autres classes, création de nouvelles librairies, changement d'algorithme... Si l'on ajoute à ces changements, le manque de temps, la mise à jour de la documentation passe à la trappe.

Le problème de mise à jour de la documentation a un autre effet pervers : une personne qui consulte la documentation n'a pas connaissance du niveau de mise à jour de celle-ci, un doute persiste concernant l'exactitude des informations qui s'y trouvent. Il se peut que suite à de nombreuses expériences négatives (documentations obsolètes), une personne puisse prendre l'habitude de lire directement le code source car c'est la seule source d'information dont l'exactitude soit certaine.

3   Solutions existantes

3.1   Quelques bonnes pratiques

Quelques bonnes pratiques peuvent aider fortement à la bonne tenue de la documentation :

  • la documentation doit être le plus près possible du code source

    En pratique, il est plus facile de tenir à jour la documentation quand celle-ci est intégrée dans le code source.
    En Python, les docstrings permettent d'intégrer la documentation à l'intérieur du code source. La documentation est au plus près du code, lorsque le code est modifié le développeur est mieux à même à mettre tout de suite à jour la documentation.
    Lorsqu'une documentation n'est pas sujette à être intégrée dans le code source, une bonne pratique est de l'intégrer dans un fichier texte enregistré dans le répertoire qui correspond le mieux avec la partie du projet qu'elle documente.
    Par exemple, si le fichier documente l'utilisation d'une librairie, il est judicieux d'enregistrer la documentation à la racine du code source de la librairie.
    Si la documentation traite du projet dans son ensemble, il est judicieux d'enregistrer le fichier à la racine du projet...
    L'idée est toujours la même : garder la documentation le plus près possible du code qu'elle documente.
  • la documentation doit être facilement modifiable

    Généralement, les développeurs utilisent un éditeur texte (plain text) pour éditer du code source. La documentation doit être éditable aussi facilement que le code source du programme. C'est pour cela qu'il est conseillé d'écrire la documentation au format texte (plain text) plutôt que dans un format spécifique comme Writer d'OpenOffice.org...
    En Python, le format communément utilisé est le reSTructuredText, un format texte enrichi mais de manière non intrusif.
    Là encore, le but est de favoriser la mise à jour de la documentation en rendant sa modification le plus simple possible.
  • éviter au maximum la redondance

    Certaines informations clés qui sont au coeur de la documentation technique sont déjà présentes dans le code source du projet.
    Partant de ce constat, il peut être judicieux d'automatiser l'extraction de ces informations vers la documentation afin d'éviter la redondance et par conséquent éviter les besoins de mises à jour et les risques d'erreurs.
    La documentation peut être en partie générée à partir du code source du projet.

    Exemples pratiques :

    • génération automatique de l'API d'une librairie à partir du code source ( exemples d'outils python : Epydoc [1], Sphinx [2]);
    • génération d'un diagramme de classe à partir du code source (voir futur billet à propos de code2uml);
    • génération d'un diagramme de base de données à partir du code sql qui permet la création de la structure de la base de données (voir futur billet à propos de code2uml);
    • génération d'une liste de tâches à réaliser (todo list) à partir de marques à l'intérieur du code source (voir exemple dans Zope3 [3]). Ceci evite d'avoir deux fois la même information : une fois dans le code source à l'endroit précis où la tâche doit être réalisée et une fois dans la liste des tâches à réaliser. De plus, cette pratique a l'avantage de situer la marque d'indication de la tâche au plus près du code source.
    • Les scénarios de tests automatisés d'interfaces utilisateurs peuvent être utilisés pour générer automatiquement des screncasts des applications. Ils pourront alors être utilisés comme documentation à destination des utilisateurs finals. De plus, ils auront l'avantage d'être toujours à jour et valides (si les tests sont réalisés avec succès).
  • donner à la documentation un intérêt fonctionnel

    Une autre bonne pratique est de donner un intérêt fonctionnel aux documentations. C'est-à-dire que cette documentation doit être utile pour générer ou réaliser d'autres choses. Si la documentation automatise certaines tâches et simplifie la vie du développeur, ce dernier aura plus de motivation pour réaliser et mettre à jour sa documentation.

    Exemples :

    • Les doctests sont de bons exemples: cette documentation sert à la fois de tutoriels et de scripts de tests de bon fonctionnement du code source;
    • Un document de spécification (cahier des charges) bien formalisé peut être utilisé pour communiquer à propos de l'état d'avancement d'un projet.
[1]http://epydoc.sourceforge.net/
[2]http://sphinx.pocoo.org/
[3]http://amy.gocept.com/~ctheune/XXXreport.html

4   Est-ce que la documentation doit générer du code source ou alors est-ce que le code source doit générer de la documentation ?

Je pense personnellement que la meilleure solution est de générer de la documentation à partir du code source. Pourquoi ?
Parce que la première solution, celle qui consiste à générer du code source à partir de la documentation peut fonctionner correctement seulement lors de la phase initiale du projet. Lorsqu'il existe déjà du code source, il est difficile de modifier ce code à partir de la documentation sans prendre le risque de casser beaucoup de chose.
D'autre part, lorsqu'un développeur est pressé, correction de bug... il va toujours modifier le code source, il ne va pas modifier la documentation, exécuter une regénération... Le coeur d'un projet est toujours son code source, c'est la matière première du projet et l'on doit utiliser cette matière pour générer d'autres informations / documents... et non l'inverse.

5   Pourquoi ce billet ?

J'ai écrit ce billet car il me sert d'introduction pour un prochain billet qui traitera de mon application qui permet de générer un graphe UML à partir du code source d'un programme.

6   Outils et références

Livres :

Outils Python :

  • Epydoc : pour générer automatiquement la documentation d'une API, librairie...
  • Sphinx : outil qui permet entre autres de générer une documentation cohérente à partir de différents fichiers reSTructuredText ainsi qu'à partir du code source d'un projet
  • doctest : outil qui permet de tester un programme à partir d'un jeu de tests écrit sous la forme reSTructuredText
blog comments powered by Disqus

Mes flux :