Traduction de l\'article de Scott Ambler pour Dr. Dobb\'s Journal

1. Flash Spécial : les Agilistes écrivent de la
documentation!
Scott W. Ambler
Contrairement aux idées reçues …
Qui a dit que les Agilistes ne documentent pas ? Scott étudie les véritables pratiques des équipes
agiles.
Scott travaille en qualité de Practice Leader Agile Development pour IBM Rational.
Traduction par Emmanuel Hugonnet de l’article quot;Newsflash: Agilists Write Documentation!quot; avec
l’aimable autorisation de Scott Ambler et de Jon Erickson du Dr. Dobb’s Journal.
Vous avez probablement entendu, voire pire propagé, certains des mythes sur la modélisation et la
documentation des projets agiles. Par exemple, le mythe selon lequel les agilistes 1ne mettent en
place aucune architecture, une idée reçue qui ne tient pas bien longtemps vu que les tous les
systèmes ont forcément une architecture quelque soit la méthode de développement mise en œuvre.
Un autre de ces mythes est le fait que les agilistes ne commencent pas par modéliser les grandes
lignes d'un projet, mais où avez-vous vu que l'on finance un projet de développement sans savoir
comment le réaliser ? Apparemment les agilistes ne documentent pas non plus, ayant convaincu
comme par magie les utilisateurs finaux que les manuels sont inutiles, les équipes de support de
fonctionner sans documentation et l'équipe de maintenance de maintenir sans documentation
d'ensemble. Les agilistes ne tiennent pas compte d'une liste vraiment très impressionnante de
choses, je pense qu'il est plus que temps d'éclaircir ces incompréhensions et de tuer ces mythes. Ce
mois-ci je vais résumer les résultats de deux études, l'une qui se concentre plus spécifiquement sur
les activités de modélisation et de documentation des projets de développement logiciel, et l'autre
qui explore les pratiques réelles des équipes agiles. Vous verrez que la réalité est bien loin de la
rhétorique.
Commencer par modéliser les grandes lignes
L'étude quot;Dr. Dobb's 2008 Modeling and Documentation Surveyquot; a mis à jour un certain nombre
de points intéressants sur la manière dont les équipes de développement approchent la modélisation.
18% des équipes traditionnelles ne font aucune modélisation, à comparer au seulement 5% des
équipes agiles il est donc plus probable qu'une équipe agile modélise par rapport à une équipe
traditionnelle. La première approche de la modélisation se fait par l'intermédiaire de schémas pour
55% des équipes qui préfèrent dessiner pour penser ou communiquer des idées, 30% dessinant puis
conservant les schémas lorsque cela avait un sens. La majorité des équipes traditionnelles font elles
aussi des schémas, avec 33% des équipes dessinant, 33% dessinant et conservant les schémas
importants. 7% des équipes agiles utilisent des outils de modélisation (SBMT) comme ER/Win ou
Rational System Architect (RSA) dans un but de documentation, 5% pour le cycle de modélisation
et d’ingénierie, à comparer à respectivement 16% et 0% pour les équipes traditionnelles. La Figure
1 résume les résultats pour les quatre types d'équipe étudiés : ad-hoc, traditionnelle, itérative et
agile.
L'étude quot;Ambysoft 2008 Agile Practices and Principles Surveyquot; explore l'adéquation entre les
1
NdT : j’ai utilisé l’anglicisme ‘agiliste’ plutôt que de le traduire par manque d’un vocabulaire adapté. Une traduction
convenable aurait pu être ‘praticien agile’.

2. développeurs agiles et les différentes stratégies de développement. Ainsi pour connaître les
pratiques de modélisation des équipes agiles au début d'un projet la question posée était :
quot;Nous réalisons une modélisation des principales exigences au démarrage d'un projet agile
pour pouvoir budgéter et planifierquot;.
L'étude indique que 74% des personnes interrogées sont d'accord ou fortement d'accord avec cette
proposition, 18% ne se prononcent pas et seulement 8% sont en désaccord ou en profond désaccord
avec cette proposition.
De même, pour connaître leur position quant à la modélisation de l'architecture nous avons posé la
question suivante :
quot;Nous modélisons l'architecture au démarrage d'un projet agile afin de partir dans la bonne
directionquot;.
Les résultats sont quasiment identiques avec des scores respectifs de 73%, 19% et 8%. En
conclusion deux études différentes sur deux communautés différentes montrent toutes les deux que
les équipes de développement agiles, dans la pratique, modélisent.
Figure 1 : Les stratégies de modélisation suivant les méthodes de développement logiciel employées
Les équipes agiles modélisent au début d'un projet car elles doivent répondre aux mêmes questions
que les autres :
• quel périmètre doit-on adresser,
• pour quel coût,
• dans quels délais
• et avec quelle stratégie technique.
Sans des réponses cohérentes à ces questions un projet n'obtiendra tout simplement pas son budget.
Que l’on doive modéliser dès les premiers instants de la vie d'un projet, n'implique pas qu'on doive
le faire en écrivant des montagnes de documentation. On peut tirer les bénéfices de la modélisation,
à savoir communiquer et réfléchir, sans avoir à accepter les coûts d'une documentation inutile.
Une autre raison pour laquelle les équipes agiles commencent par modéliser, contrairement aux
préceptes des extrémistes de la communauté agile, est que les métaphores architecturales ne
suffisent pas. Les architectures des systèmes actuels sont complexes, elles adressent quantités
d'exigences non-fonctionnelles et de contraintes comme la performance, la sécurité, et bien d'autres

3. encore (cf. mon article d'octobre 2008 à ce sujet2). La métaphore architecturale ne va pas permettre
de réaliser le travail.
Prenez par exemple le site web de la conférence Agile 2008 (www.agile2008.org) qui a été construit
selon l'idée qu'organiser une conférence c'est comme produire une pièce de théâtre. Cette métaphore
n’était pas la bonne, rendant le site complexe à utiliser. Par exemple, pour construire votre planning
de conférences auxquelles vous souhaitiez participer, vous deviez parcourir les 19 pages du
programme officiel décrivant en détail chacune des représentations. Mortel ! Un peu de réflexion et
de modélisation en amont aurait surement permis d'éviter ce genre de problème.
Documentation Agile
L'étude quot;Dr. Dobb's Modeling and Documentation Surveyquot; a révélé qu'il n'y a guère de
différence selon l'approche utilisée lorsqu'il s'agit de produire de la documentation sous forme d’un
livrable. Après tout un livrable reste un livrable. Les craintes concernant le manque mythique de
documentation des projets agiles sont donc infondées, les traditionalistes qui résistent encore
doivent alors trouver d'autres excuses pour ne pas appliquer les stratégies agiles. Comme vous
pouvez le voir dans la Figure 2, les agilistes ont une probabilité légèrement plus faible de produire
une documentation générale du système que les traditionalistes, mais par contre légèrement plus
forte de produire une documentation opérationnelle. Je pense que cela vient du fait que le besoin
d'une documentation générale du système se ressent moins, les agilistes ayant tendance à produire
du code de bien meilleure qualité, résultat du remaniement3 et de la pratique du développement
piloté par les tests (TDD4). On peut aussi expliquer le moindre besoin de documentation des équipes
agiles par l'écriture de spécifications exécutables.
L'étude quot;Ambysoft 2008 Agile Practices and Principles Surveyquot; s’est intéressé aux interactions et
à la communication des équipes agiles, en demandant de noter l'efficacité de différents moyens de
communication avec les clients. Voici les résultats ordonnés par efficacité, le score de chacune des
techniques étant une moyenne pondérée entre 5 (très efficace) et -5 (très inefficace) :
1. Discussion en Face à Face (F2F) (4.06)
2. Face à Face (F2F) avec un tableau blanc (3.46)
3. Digrammes généraux (1.89)
4. Documentation générale (1.86)
5. Vidéo conférence (1.62)
6. Conférence téléphonique (1.51)
7. E-mail (1.32)
8. Documentation détaillée (0.16)
9. Messagerie instantanée (0.15)
On peut faire plusieurs observations intéressantes.
Premièrement, on peut comprendre la croyance des traditionalistes dans la valeur des
spécifications détaillées avec ce résultat neutre malgré tout ce que l'on peut entendre sur les méfaits
de la documentation détaillée dans les communautés agiles.
Deuxièmement, partager une documentation générale avec les clients semble avoir un
certain intérêt, même si c'est loin d'être aussi efficace qu'une communication directe, ce qui fait
mentir les préjugés sur la documentation agile.
Troisièmement, la théorie de la richesse du média, qu’Alistair Cokburn a introduite dans la
communauté agile tient la route (cf. www.agilemodeling.com/essays/communication.htm). Le
moyen de communication le quot;plus chaudquot; semble être généralement le plus efficace.
2
NdT : cet article est disponible en français à l’adresse :
3
NdT : refactoring.
4
NdT : Test Driven Development

4. Quatrièmement, ces résultats peuvent expliquer pourquoi les projets agiles avec des équipes
distribuées semblent être plus risqués que les projets où les équipes sont regroupées, car plus les
équipes sont distribuées et plus le choix de moyens de communication est restreint. L'étude quot;Dr
Dobb's Agile Adoption Surveyquot; (cf. www.ddj.com/architect/207600615) avait montré que les
chances de succès d'un projet agile variaient de 83% pour une équipe regroupée, 72% pour des
équipes peu distribuées à 60% pour des équipes distribuées.
Figure 2 : Les probabilités de produire un livrable de documentation suivant les méthodes de développement
logiciel employées.
Bonnes Pratiques de la Modélisation et la Documentation Agile
Maintenant que l’on tient pour acquis le fait que les développeurs agiles modélisent et écrivent de la
documentation, on peut se demander pourquoi ces mythes persistent encore. Je pense qu'il y a à cela
trois raisons principales.
Premièrement, la communauté agile se bat pour essayer de décrire de manière cohérente ses
pratiques. Par exemple, si on mentionne la modélisation d'une vision globale du projet sur les listes
de discussion agiles la conversation évolue rapidement vers les méfaits de la modélisation détaillée
du projet comme première étape obligée (BDUF) et le poids de la bureaucratie avec virtuellement
aucune information sur ce que les pratiques réelles des équipes.
Deuxièmement, beaucoup de traditionalistes ont peur de l'approche agile du développement
logiciel, car elle demande d'autres compétences et souvent plus de discipline pour réussir. Les
quot;nouvelles règlesquot; du développement agile inquiètent naturellement ceux qui ne les connaissent pas
bien ou qui n’ont pas eu l'opportunité d'effectuer la transition.
Troisièmement, le manque de spécifications détaillées au démarrage d'un projet agile, peut
laisser croire que les équipes agiles ne modélisent pas à des traditionalistes ne connaissant pas
l'approche Développement Piloté par la Modélisation Agile (Agile Model Driven Developpement).
Par exemple, nous avons vu dans la Figure 1 que les équipes agiles modélisent plus fréquemment
que les traditionalistes, qu'elles préfèrent les schémas et les dessins à de la documentation détaillée
produite par un logiciel de modélisation (SBMT). Des différences comme celle-ci peuvent être mal
interprétées si on n'est pas familier des stratégies disciplinées des équipes agiles.

5. Il y a quantité de ressources en ligne qui décrivent comment les équipes agiles approchent la
modélisation et la documentation. Les bonnes pratiques AMDD sont
• de commencer par recueillir les exigences initiales et de se forger une vision globale de
l'architecture dès le début du projet pour pouvoir écrire des spécifications exécutables selon
une approche de Développement Piloté par les Tests (TDD),
• d’éviter de dupliquer l’information autant que faire se peut,
• d'écrire la documentation plus tard dans le cycle de vie du projet,
• de promouvoir l'implication des clients, de réaliser les exigences selon leur priorité,
• d'inclure la modélisation dans le planning de l'itération / du sprint,
• de produire des modèles et de la documentation juste suffisants pour la situation courante,
• de modéliser les détails en groupe en mode Juste à Temps (JIT),
• parfois de modéliser à l'avance pour certaines exigences complexes,
• et d’utiliser différentes formes de modélisation et de représentation.
On peut trouver une description de l’ensemble de ces bonnes pratiques sur
www.agilemodeling.com/essays/bestPractices.htm.
Nous devons mieux faire
On peut tirer profit des pratiques de modélisation et de documentation efficace, cependant de
nombreuses organisations n'en retirent aucun bénéfice. L'étude quot;Dr. Dobb's Modeling and
Documentation Surveyquot; indique que 80% des développeurs apprennent la modélisation sur le tas,
28% en étant encadré par une personne rompue à la modélisation, 18% à l'université, 9% en suivant
une formation à la modélisation, et 5% en suivant une formation à un outil de modélisation. Il me
semble que si notre apprentissage de la modélisation était moins hasardeuse, alors celle-ci serait
entourée de moins de mythes et d'incompréhensions et plus important encore les pratiques et les
outils de modélisation pourraient être mis en œuvre de manière beaucoup plus efficace.
Annexe : les études
En juillet 2008, j'ai effectué deux études pour savoir ce qui se passe réellement dans les équipes de
développement.
L'étude quot;Dr. Dobb's Modeling and Documentation Surveyquot; porte sur les lecteurs du DDJ, ce qui
couvre les pratiques de développement depuis les traditionnelles jusqu'aux pratiques ad-hoc. Nous
avons utilisé la liste de diffusion du Dr. Dobb's et le blog de Jonathan Erickson pour en faire la
publicité afin que les gens répondent au questionnaire. 279 personnes y ont répondu, dont 54.8% de
développeurs et 25.4% de managers. En ce qui concerne l'expérience du monde de l'informatique,
33.3% avaient entre 10 et 20 ans d'expérience et 41.6% en avaient plus de 20. Les données
originales (sans les informations personnelles), les questions telles quelles étaient posées et le
résumé de l'enquête sous forme de diapositives sont disponibles sur
www.ambysoft.com/surveys/modelingDocumentation2008.html.
L'étude quot;Ambysoft 2008 Agile Practices and Principles Surveyquot; a été réalisée la dernière semaine
de juillet, et s'est concentrée sur les équipes de développement agile. L'enquête a été annoncée sur
les listes de diffusion Agile Modeling, Agile Database, Extrem Programming, Agile Project
Management, et Scrum Development. 337 personnes y ont répondu dont 37% de développeurs et 37
de managers, 42% avaient entre 10 et 20 d'expérience en informatique et 17% avaient plus de 20
ans d'expérience. Les données originales, les questions et les diapositives résumant les résultats sont
disponibles sur www.ambysoft.com/surveys/practicesPrinciples2008.html.