Mes recherches de dilettante m'ont donné la perception que les trois choses les plus importantes pour plus de qualité et d'effectivité sont la connaissance, la connaissance et la connaissance. Le savoir s'acquiert mieux avec le dialogue, mais le dialogue n'est effectif qu'avec un sachant. Hélas, il y a des situations où une telle personne n'est pas là.
Cette article vous aidera à écrire de la documentation efficace et utile pour ces situations où elle est la seule source de connaissance disponible. Les pratiques présentées dans cet article sont basées sur mes expériences de projet dans des grandes multinationales.
Tout a commencé quand un développeur expliqua qu'il avait une idée pour améliorer la documentation d'un projet. Nous avons réuni une équipe de personnes intéressées par le sujet et nous nous sommes mis d'accords sur quelques règles.
Les règles pour une Superbe Documentation
La documentation devrait :
- Être facile et rapide à créer et à mettre à jour. Une information hors d'âge peut être pire que son absence totale.
- Fournir facilement des réponses correctes. Si c'est compliqué de trouver, personne ne s'en servira.
- Ne pas remplacer les interactions humaines. Privilégier les individus et les interactions sur les processus et les outils, n'est-ce pas ?
Pour atteindre l'objectif et réaliser ces règles, nous avons positionné six pratiques :
Pratique 1 – Identifier les clients et leurs raisons d'utiliser la documentation
Alors que cela paraît évident, peu le font. Pour notre projet, notre équipe d'amélioration identifia quatre groupes.
- Les managers qui ont besoin d'un résumé du travail en cours.
- Les nouveaux développeurs qui ont besoin d'une introduction rapide.
- Les anciens développeurs du système qui reviennent après plusieurs années à faire autre chose.
- Le support qui aide les clients à résoudre leurs problèmes.
Le premier groupe fut particulièrement content quand nous leur demandâmes leurs besoins en termes de documentation. D'abord, personne ne l'avait jamais fait avant. Wow ! Ensuite, ils n'avaient jamais regardé la documentation imposante à disposition. Ce groupe n'attend que trois réponses. Au final, ils n'avaient besoin que de trois lignes de documentation. Le reste n'était que du gaspillage pour le lecteur et le rédacteur. OMG !
Pratique 2 – Structurer la documentation comme Google Earth
Les gens utilisent de la documentation pour trouver des réponses aux questions qu'ils ont. La qualité de la documentation peut être mesurée par la temps requis pour trouver une réponse. Nous avons utilisé Google Earth comme modèle.
Avez-vous déjà essayé de trouver votre maison sur Google Earth (en scrollant, pas en mettant votre adresse) ? Combien de temps faut-il ? 30 à 60 secondes ? Trouver votre maison sur la surface de la Terre est équivalent à chercher une réponse parmi 1,5 Milliards (1,5 * 10 12). Si vous cherchez une réponse, cela ne devrait pas prendre plus de 60 secondes, même si votre système est complexe et énorme.
Comment applique-t-on cela à la documentation ? Nous avons suivi une structuration similaire aux niveaux dans Google Earth : niveau de la lune, du satellite, de l'avion, de l'hélicoptère, etc. Chaque niveau propose une description courte, appelée pitch, et propose jusqu'à neuf possibilités pour continuer la descente.
Gardez à l'esprit que tous les outils de documentation ne supportent pas cette approche en entonnoir. Une structure en répertoire avec des documents Word n'est sans doute pas une bonne idée. Un wiki avec des liens sur les niveaux inférieurs s'y prête mieux.
Pratique 3 – On reste petit
Nous discutâmes de la raison d'être de la documentation et en sommes arrivés aux principes suivants pour en limiter la taille :
- La documentation devrait servir à communiquer sans contraintes de temps ni de lieux. Elle ne remplace pas la communication en temps réel.
- Nous devrions uniquement documenter les résultats, pas les besoins. Cela implique de mettre à jour ou remplacer les documents lors du lancement d'une nouvelle fonctionnalité, et non au moment de l'expression d'un besoin. Ceci permet à la documentation de refléter précisément l'état du système.
- Le bénéfice de la documentation devrait être supérieur à son coût de création et de maintenance. Ne perdez pas de temps à documenter ce qui est écrit dans le code. La documentation devrait fournir une vision d'ensemble, et assez d'informations pour aider le lecteur à trouver rapidement la réponse dans le code.
Le bon niveau de documentation est l'équilibre entre trop peu pour être utile et trop long pour la lire. Si vous ne l'utilisez pas, vous ne la mettrez pas à jour et donc ça ne vaut pas le coût, voire même dangereux si elle est obsolète et fausse.
Voici un conseil de Henrik Kniberg :
- Ayez aussi peu de documents que possible - mais pas moins.
- Ayez des documents aussi courts que possible - mais pas moins.
C'est aussi simple que ça :-).
Pratique 4 - Ecrivez pour donner envie de lire
Un texte long et non pertinent est pénible. Comment le rendre attrayant ?
Nous avons essayé ceci : nous avons demandé à un client potentiel d'interroger une personne sachante. Le lecteur sait ce qu'il veut savoir et la manière de structurer le texte mieux que l'expert. Celui-ci ne peut qu'imaginer ce que l'autre veut savoir et comment le présenter.
L'anti-pattern type est quand quelqu'un quitte l'entreprise et que son manager lui demande de documenter tout ce qu'il sait avant de partir. Pour la plupart des gens, c'est plus une punition qu'un travail à valeur ajoutée.
Pratique 5 – Mettez des schémas
Même si le texte devrait être court, en plongeant dans le détail, au niveau des feuilles, le texte pourrait s'allonger et présenter plus de détails. Comment y arriver sans perdre le lecteur ? Appelons les magazines scientifiques à la rescousse ! Plutôt que d'écrire votre documentation comme un article scientifique, vulgarisez le texte comme dans les magazines, avec beaucoup de schémas et des paragraphes courts et faciles à lire.
Avec des schémas, l'utilisateur de la documentation trouve plus vite ce qu'il cherche. L'oeil du lecteur va d'une image à l'autre comme à la lecture d'un journal.
Pratique 6 - Rendez la mise à jour facile
Le plus grand challenge dans l'écriture d'une bonne documentation est de la garder à jour.
Cela implique de la discipline et une simple règle de Boy Scout, "Laissez toujours le camp plus propre que vous ne l'avez trouvé". Avec la documentation, cela signifie que si vous n'avez pas l'information qu'il vous faut, mettez-la à jour avec les bonnes informations dès que vous l'avez trouvé.
La probabilité de conserver de la documentation à jour décroit avec l'augmentation de la distance entre ce qui change et l'endroit pour le décrire. Les commentaires dans le code sont l'endroit le plus proche du changement, et donc avec une plus forte chance de mise à jour qu'un document présent ailleurs. Si vous utilisez un wiki pour votre documentation, vous pouvez facilement y intégrer les commentaires de code.
Si la documentation est difficile à maintenir, ou ne peut être mise à jour dès qu'un problème apparaît, la probabilité est forte qu'il n'y en ait pas. Utilisez un outil pour une mise à jour facile ou simultanée. Il en va de même pour les images, donc vérifiez que les outils utilisés permettent directement de créer et mettre à jour. MediaWiki avec PlantUML et Confluence couplé à Gliffy en sont deux exemples.
Le Résultat
Notre documentation a passé un test quand un nouveau groupe de personnes travaillant dans une autre ville a demandé un changement de code sur une partie maintenue par notre département. Une courte introduction et un courriel avec un lien vers la zone de documentation fut notre seul contact, et nous fûmes surpris de constater que c'était la seule attente. Nous avions atteint notre objectif. Nous avions une documentation facile et rapide à créer et à maintenir, et qui aide efficacement les utilisateurs à trouver les réponses dont ils ont besoin.
J'espère que nos règles et pratiques vous aideront à créer une meilleure documentation.
Bonne Chance !
Avertissement : le terme Lean dans le titre n'a rien à voir avec Toyota. J'utilise ici le sens de l'adjectif lean (signifiant efficace et sans gaspillage).
Merci à Ellen Gottesdiener pour son soutien et son aide. Merci à Jonas Boegård, Henrik Rasmussen et Igor Soloviev pour toutes leurs bonnes idées. Merci aussi à Mia Starck et Yassal Sundman pour leur aide sur la langue.
Note : le “connaissance, connaissance et connaissance” du premier paragraphe se rapporte à : connaissance du domaine (connaître le métier), connaissance du système (connaître le domaine et l'architecture du système) et la connaissance immédiate des besoins produit (connaître ce que nous allons construire maintenant). La méthode de documentation décrite ici est surtout orientée pour la connaissance du domaine et du système, et pour faire un pont entre le deux.
A propos de l'Auteur
Tomas Björkholm est coach agile et formateur chez Crisp à Stockholm, Suède. Il adore faire mûrir les équipes, en particulier dans les grandes entreprises. Sa mission est de rendre l'Agile facile à comprendre et à adapter. Tomas a écrit deux livres, un guide sur l'Agilité en suédois et publiera bientôt "Le développement Kanban en 30 jours".