documentation agile

Les choses à faire et à ne pas faire en matière de documentation agile

Temps de lecture : environ 10 min

Au cours des deux dernières décennies, les équipes sont passées d’un mode de travail en waterfall à un mode de travail agile, ce qui a entraîné une stigmatisation de la documentation. 

De nombreuses équipes ont mal interprété le principe du Manifeste agile selon lequel « un logiciel fonctionnel est plus important qu’une documentation exhaustive » et que l’ont traduit par « aucune documentation ». S’il est vrai que les approches classiques de la documentation sont inefficaces, son élimination pure et simple peut nuire aux équipes agiles, d’autant plus que le télétravail et le travail hybride deviennent de plus en plus courants. 

Imaginez que vous essayez de construire une maison. Peu importe que vous soyez rapide, incrémentiel ou efficace : si vous ne vous occupez jamais de la charpente et des fondations, la maison ne tiendra pas longtemps debout. De la même manière, la documentation fournit aux équipes agiles les bases nécessaires pour apprendre, s’adapter, innover et apporter de la valeur aux clients. Sans elle, ces équipes agiles peinent à s’harmoniser, sont sujettes aux erreurs et aux problèmes de communication. Elles manquent d’efficacité et ne disposent pas du contexte nécessaire pour prendre des décisions et s’adapter aux fluctuations du marché. 

En d’autres termes, si l’élimination de la documentation semble être un moyen d’accroître temporairement l’agilité, dans les faits, elle la réduit de manière significative à long terme.

Plutôt que de se débarrasser complètement de la documentation, les équipes ont désormais tout intérêt à l’améliorer. La solution ne consiste pas à revenir à la façon dont la documentation était abordée à l’époque du Waterfall. Les équipes doivent adopter une approche organique, dynamique, adaptable et hautement visuelle de cette pratique.

À quoi ressemble une approche agile de la documentation ?

Une approche agile de la documentation suit plusieurs des mêmes principes que le manifeste agile lui-même. En d’autres termes, elle doit être itérative, adaptable et collaborative. L’objectif d’une documentation agile efficace devrait être de :

  • Mieux partager le contexte entre les équipes hybrides et éliminer les échanges inutiles
  • Permettre une mise sur le marché plus rapide grâce à la modélisation de processus reproductibles
  • Créer une expérience d’intégration efficace pour les nouveaux employés

Compte tenu de la complexité croissante des entreprises – plus de logiciels, plus de données, un rythme de changement accéléré et l’adoption exponentielle du travail distribué – les organisations ne peuvent pas se permettre de renoncer à la documentation : c’est une nécessité pour travailler efficacement et innover continuellement.

Et à l’heure où les entreprises sont confrontées à des restrictions budgétaires, au renouvellement du personnel et à d’autres menaces pour leur activité, une meilleure documentation permet d’éviter que des connaissances précieuses ne s’échappent de votre entreprise.

Quels exemples peut-on donner de la documentation agile ? 

La documentation agile se compose de documents, de diagrammes ou de modèles simples à comprendre, très visuels, qui aident les équipes à prendre des décisions et à aller de l’avant. Cela peut inclure :

Si ces documents sont importants pour maintenir la cohésion des équipes, il existe aussi des moyens moins formels de recueillir des informations, qui sont tout aussi essentiels pour assurer une innovation continue.

Par exemple, si vous organisez vos événements agiles à distance, utilisez une salle d’équipe virtuelle pour capturer vos idées, vos obstacles ou vos commentaires. Cet espace virtuel sert de documentation dynamique et permet d’enregistrer le contexte et les décisions du projet.

espace multisalles pour équipe scrum
Modèle d’espace multisalles pour équipe Scrum (cliquez pour le modifier en ligne)

Les choses à faire et à ne pas faire en matière de documentation agile

En gardant tout cela à l’esprit, voici quelques conseils stratégiques pour aborder votre documentation agile :

À faire : documenter continuellement votre travail

La documentation est souvent critiquée comme étant un processus intensif qui prend du temps sur le travail réel de programmation et de développement du produit. Pour autant, ce n’est pas une fatalité.

Un article récent d’InfoQ propose une approche de la documentation continue qui repose sur le couplage de votre documentation à votre code et sur le moment choisi pour la rédiger – par exemple, immédiatement après la correction d’un beugue, plutôt que suivant l’achèvement d’un grand projet. Et les articles de Lucid sur les référentiels d’innovation suggèrent une approche permettant de transformer tout le travail de brainstorming, de planification et d’exécution que vous effectuez déjà en un « modèle vivant » de la manière dont votre entreprise concrétise ses meilleures idées.


Envisager la documentation de cette manière en fait une extension naturelle du processus de conception, de programmation, de sécurité, de test, de vente et de marketing, et non une tâche distincte que l’on accomplit à contrecœur. Il est également plus efficace de documenter votre travail au fur et à mesure, car vous pouvez prendre des notes sur les processus pendant qu’ils sont encore frais dans votre tête.

Ne pas faire : créer de la documentation par principe

Tout au long du processus de documentation agile continue, il est important de vous poser les questions suivantes pour éviter d’entrer dans une pratique sans intérêt :

  • Quel est l’objet de cette documentation ?
  • À qui s’adresse ce document, et comment sera-t-il utilisé ? 
  • Ce document existe-t-il déjà ailleurs ?

Adopter un état d’esprit de documentation agile continue ne signifie pas que vous devez réaliser un travail redondant. Au contraire, il convient de rechercher les occasions de compléter et d’améliorer des documents existants chaque fois que cela est possible.

La résolution des problèmes de version, l’optimisation d’un document difficile à trouver ou à lire pour en faciliter la découverte et la compréhension, ou l’ajout de captures d’écran et de diagrammes à un document riche en texte sont autant de moyens importants de renforcer la base de connaissances de votre entreprise au-delà de la simple création de nouveaux documents.

À faire : automatiser la documentation lorsque c’est possible

L’ajout d’une base de données et d’autres intégrations peut réduire les erreurs et les malentendus qui surviennent lorsque vous devez mettre à jour votre documentation manuellement, en particulier pour les diagrammes entité-association (EA) ou toute autre documentation représentant des relations de données complexes. 

L’automatisation peut également vous permettre de gagner du temps et d’économiser des efforts en actualisant des parties clés de votre documentation sans même que vous y pensiez (ou que vous sachiez que cela se produit). Le fait d’avoir les données les plus récentes à portée de main plutôt que de devoir les chercher peut vous aider à générer plus efficacement des informations exploitables et à découvrir des schémas que vous n’auriez peut-être pas remarqués autrement.

Ne pas faire : attendre la fin de votre projet pour le documenter

Attendre la fin d’un projet pour le documenter présente le risque d’oublier des informations, augmente la marge d’erreur et ajoute une charge inutile au terme d’un sprint laborieux, lorsque l’enthousiasme pour accomplir « encore une petite chose » n’est plus vraiment au rendez-vous.

En abordant la documentation agile sous l‘angle de la création d’un référentiel d’innovation à la fois sur le moment et dans le temps, celle-ci devient une composante naturelle du projet – de l’idéation et de la planification à la conception et au lancement – plutôt qu’une tâche marginale ajoutée à la fin.

Ne pas faire : produire des documents de manière cloisonnée

Il n’est pas efficace de passer du temps à créer des documents individuellement, puis d’attendre que le projet soit bien avancé pour recueillir des commentaires. Si le périmètre de votre documentation est erroné ou si des détails essentiels manquent, un remaniement important risque de s’imposer, travail qui aurait pu être évité.

Le fait d’impliquer vos collaborateurs dès le début, par le biais d’entretiens ou de réunions visant à déterminer la documentation réellement nécessaire, ou en coopérant sur les documents eux-mêmes, vous fera gagner du temps et vous épargnera des difficultés par la suite.

À faire : créer de la documentation en collaboration avec l’équipe

La documentation ne doit pas être un travail solitaire, surtout lorsque vous la rédigez à partir d'un code, de tableaux de brainstorming, de cartes de planification ou d’autres documents que vous avez déjà créés en équipe.

Le fait d’impliquer d’autres personnes dans le processus permet de les sensibiliser et d’obtenir leur adhésion en adoptant une approche collaborative. Cela génère également un sentiment de responsabilité collective quant à la rigueur de la documentation dans votre organisation et renforce l’importance de la mise à jour des documents pour l’équipe. Pour les employés les moins expérimentés, participer au processus de création peut également être une expérience d’apprentissage très enrichissante.

Modèle de recherche utilisateur et cartographie de parcours
Modèle de recherche utilisateur et de cartographie de parcours (cliquez pour le modifier en ligne)

La fréquence des mises à jour de la documentation et le travail de communication et de distribution nécessaire pour s’assurer que chaque personne est au courant de la publication d’une nouvelle version est l'une des principales difficultés de la documentation.

Une solution de stockage cloud (de préférence une formule qui permet de faire de la collaboration visuelle et rends les informations encore plus compréhensibles) vous évite de devoir gérer les problèmes de versions et garantit que les membres de l’équipe ont accès aux informations dont ils ont besoin pour prendre des décisions rapidement et en toute confiance.

Ne pas faire : utiliser la documentation pour remplacer les échanges

Si une documentation claire et visuelle peut faciliter le travail asynchrone, elle doit compléter les échanges et non les remplacer. Créer une documentation plus efficace ne signifie pas que vous n’avez plus besoin de collaborer avec vos coéquipiers : il s’agit de renforcer ces liens et d’alimenter des conversations qui débouchent sur une réflexion et une innovation révolutionnaires.

Rappelez-vous ce principe agile : La meilleure forme de communication est le dialogue en face à face.

À faire : utiliser des éléments visuels simples et attrayants

Une documentation qui privilégie les éléments visuels par rapport au texte permet de clarifier des informations complexes, de présenter plus clairement les associations entre les entités et d’être plus facilement assimilable en un coup d’œil par les parties prenantes.

Imaginez que vous rejoignez une nouvelle entreprise et que vous découvriez que son organigramme est entièrement rédigé sous forme de liste à puces. Il n’y a pas de hiérarchie, de niveaux ou de lignes indiquant les rapports de subordination, juste une liste de noms et d’intitulés de poste – et c’est à vous de faire le gros du travail pour comprendre les relations entre les différents collaborateurs et équipes.

Bien qu’il s’agisse d’un exemple un peu extrême, le même principe s’applique à l’utilisation de visuels pour tout type de documentation. Des visuels clairs évitent au lecteur d’avoir à fournir des efforts pour comprendre des structures, des liens et des dépendances complexes, ce qui lui permet de se concentrer sur ses véritables responsabilités professionnelles.

Organigramme par localisation
La visualisation des informations, par exemple par le biais d’un organigramme, aide à clarifier des informations complexes.

Ne pas faire : créer des documents trop denses et chargés en texte

En essayant d’être exhaustif dans votre documentation et de consigner toutes vos idées sur papier, il est facile d’oublier que vous ne rédigez pas nécessairement la documentation pour vous-même. Lorsque vous écrivez pour vous-même et non pour d’autres personnes, vous pouvez avoir tendance à passer à côté d’étapes importantes, à manquer des informations essentielles ou à les noyer dans un gros volume de texte.

Le problème est que vous vous retrouvez souvent avec un document qui peut avoir du sens pour vous – parce que vous avez une expertise et connaissez le contexte du processus – mais qui reste inaccessible pour quelqu’un qui aborde le sujet pour la première fois.

Si vous constatez que la rédaction de votre documentation prend régulièrement beaucoup de temps, c’est peut-être que vous êtes trop prolixe. Si la documentation est si dense qu’elle devient confuse et n’est pas utilisée, elle ne présente pas d’intérêt. Plus c’est simple, mieux c’est.

documentation agile

En savoir plus sur l’importance de repenser la documentation.

Téléchargez notre livre électronique

À la une

Zoom’s Lucidspark Zoom App integrationRenforcer la collaboration grâce à Lucidspark et Zoom

À propos de Lucidspark

Lucidspark est un tableau blanc virtuel qui vous aide, vous et votre équipe, à collaborer pour mettre en lumière vos meilleures idées. Ses nombreux outils, tels que les post-its ou le dessin à main levée, ainsi que sa zone de travail illimitée, vous permettront de faire émerger vos meilleures idées. Bien entendu, il est entièrement conçu pour la collaboration. C'est un espace libre où les membres de votre équipe peuvent s'échanger des suggestions, développer mutuellement des idées et innover en temps réel.

Développé par les créateurs de Lucidchart, partenaire de confiance de plusieurs millions d'utilisateurs dans le monde, dont 99 % des entreprises du Fortune 500.

Démarrer

  • Tarifs
  • Individual
  • Team
  • Entreprise
  • Contacter le service commercial
ConfidentialitéMentions légalesCookies

© 2022 Lucid Software Inc.