vendredi 25 juillet 2008

Documentation documentation ....

Les aller-retours permanents entre le code et la documentation sont pour moi une perte de temps et d'énergie (Muda selon Lean). D'ailleurs c'est pour cette raison qu'XP préconise de réduire au maximum la documentation et de la faire au plus près du code.
Qui n'a pas utilisé le retro-engineering des outils UML pour produire les diagrammes nécessaires plutôt que de les maintenir au fur et à mesure du développement ?
D'où l'idée qui coniste à produire automatiquement la documentation à partir du code, ainsi on aurait une documentation continue et toujours en adéquation avec le code. C'est d'ailleurs ce que propose Paul Duvall dans son dernier article "Automation for the people: Pushbutton documentation".
Dans le même esprit j'avais déjà expérimenté UMLGraph mais cela restait laborieux. L'outil Apiviz semble un pas en avant vers la bonne solution. J'espère le tester rapidement ;o)
Bon week-end.

2 commentaires:

Miguel a dit…

Paul Duvall n'a rien inventé.
Il ne fait que reprendre les idées de Donald Knuth avec le Literate Programming sans le savoir (apparemment il ne connaît pas cette approche).

La valeur qu'il rajoute ici est une approche différente du literate programming de celle pratiquée par Donald et qui utilise les outils existants.
Ce qui est vraiment intéressant est effectivement sa solution avec docbook.
Le reste ... bof.

Je voudrais aussi rappeler que Doxygen (qu'il énonce dans son billet) permet déjà de produire des diagrammes UML du code.

ehsavoie a dit…

1/ Ce que Paul Duvall apporte concerne l'automatisation des tâches lors du développement, la documentation n'en est qu'une.
2/ Docbook = no comment ;o) Mais franchement c'est pas clair pour moi (trop de tags 'redondants') et des éditeurs limités.
3/ L'intérêt ici est d'avoir les diagrammes UML dans la Javadoc.

L'approche n'est donc pas révolutionnaire mais évolutionnaire .... Et comme on dit par chez moi:
It's evolution baby
Do the evolution ....