La documentation en mode Agile

Publié par Jean-Francois Gilbert le vendredi 15 juin 2012 à 08:00

Une des zones grises dans les méthodes Agiles se situe au niveau de la documentation. Selon le manifeste Agile, on préfère “des logiciels opérationnels plus qu'une documentation exhaustive”. Les gens ont souvent tendance à interpréter cela comme une invitation à ne pas documenter. Pourtant, la documentation a sa place dans un projet Agile mais il faut se poser quelques questions avant d’écrire un document.

  1. Pourquoi écrire ce document ?

Ça peut paraître bête mais il faut parfois remettre en question l’existence même d’un document. Si personne dans votre équipe n’est en mesure d’expliquer pourquoi un document doit être écrit, c’est probablement que vous n’en avez pas besoin ! Si le document n’est pas totalement inutile, revoyez quand même son contenu. Par exemple, est-ce qu’une analyse destinée uniquement aux développeurs a besoin d’un sommaire exécutif de 5 paragraphes ?

Ne soyez tout de même pas trop prompt à laisser tomber votre documentation. Parfois elle a vraiment sa raison d’être. La vie d'un logiciel ne se termine évidemment pas à sa livraison. Une équipe totalement différente peut prendre en charge le support. On ne peut s'attendre à ce qu'ils regardent uniquement les tests unitaires pour comprendre le fonctionnement de l’ensemble de l'application. Même à l’intérieur de l’équipe, tout ne peut être transmis oralement. On ne peut pas non plus demander des PO ou analystes de connaître par cœur toutes les règles d’affaires.

  1. Combien de temps ce document doit-il exister ?

Pendant une phase de design, il est parfois bien utile de mettre sur papier des diagrammes ou toute autre information importante. Une ébauche d’architecture faite sur un coin de table peut parfois devenir un document officiel. Le hic c’est qu’il n’est peut-être plus très près de la réalité après quelques temps. Il vous a été utile mais vous n’en avez plus besoin ? Vous ne voyez pas l’utilité de le garder à jour ? Allez-hop, dans la poubelle ! Un document inexact est souvent pire qu’un document absent.

  1. Est-ce que c’est la meilleure façon de communiquer l’information ?

Parfois, des règles d’affaires complexes doivent être écrites car personne n’arrive à se les rappeler. Très bien, mais trouvez le bon format de document. Un bon vieux diagramme d’activité (UML) peut souvent mieux illustrer un processus qu’un long paragraphe de texte. Une matrice de données dans Excel, un prototype d’écran dessiné avec Paint, un diagramme dans Visio, le format importe peu. Mais posez-vous la question avant de l’écrire : Est-ce qu’il y a une façon plus simple de communiquer l’information ? Si vous aviez un standard de document et que ce n’est pas la meilleure façon de communiquer l’information, il est temps de remettre en question ce standard.

  1. Si le document mérite d’être conservé, comment s’assurer qu’il restera à jour ?

Le problème de désuétude et d’inexactitude de la documentation présente un défi. Il est évident que si on est capable d’atteindre une certaine stabilité dans les spécifications, il y aura moins de changements à apporter aux documents. Un truc pour s’assurer de garder la documentation synchro avec le logiciel est d’ajouter la mise à jour de la documentation à la définition de « complété ». Plutôt que d’attendre à la fin et de perdre le fil de ce qui a été modifié, on met à jour la documentation au fur et à mesure que l’on complète les users stories.

En conclusion, comme c’est souvent le cas dans les méthodes Agiles, il n’y a pas de règles strictes sur ce qui doit être documenté, et comment on doit le faire. Il faut trouver ce qui est « juste assez » et le bon type de document pour régler le bon problème dans votre équipe.

blog comments powered by Disqus

0 Comments:

Post a comment

Comments have been closed for this post.