Les développeurs détestent vraiment passer du temps à écrire, à moins que ce qu'ils écrivent soit du code. Ils ont, cependant, de bonnes raisons pour cela.
- Si ce n'est pas du code, ça ne peut pas être passé dans le compilateur pour être sûr que ça ait du sens.
- Si ce n'est pas du code, on ne l'exécute pas, donc ça pourrait ne jamais servir à rien.
- Si ce n'est pas du code, on ne peut pas le tester, donc il n'y a aucun moyen de prouver que c'est fiable et correct.
- La documentation Agile même reléguée au second plan dans le Manifesto : Des logiciels opérationnels plus qu'une documentation exhaustive.
Alors, toute documentation est-elle mauvaise ? Je pense que vous connaissez la réponse.
Pourquoi Mettre les Choses par Ecrit ?
Il y a de nombreux moments dans la vie d'un projet où une petite documentation fait beaucoup de chemin. Mais pour obtenir ces bénéfices, les développeurs doivent prendre du temps hors programmation pour mettre les choses par écrit. Voici quelques exemples où, je pense, ils trouveront un intérêt à le faire.
Se Rappeler Pourquoi on a Pris une Décision
Si un projet dure beaucoup plus longtemps que quelques mois, il y aura des moments où les décisions prises changeront le cours du développement. Il peut s'agir de la décision d'utiliser (ou d'éviter) un outil particulier, un framework, ou une plateforme. Il peut s'agir de la décision d'écrire les tests d'une certaine façon, ou de ne pas les écrire du tout dans certains cas. Il peut s'agir de la décision de se défaire de toutes les pratiques normalement utilisées et faire les choses d'une manière complètement différente. Ces décisions arriveront et elles auront tendance à durer.
Un jour, longtemps après la prise de ces décisions, quelqu'un de l'équipe (habituellement un nouveau membre, ils sont ennuyants, n'est-ce pas ?) demandera "Pourquoi faites-vous cela ?". Quelle réponse lui donnera-t-on ?
Si une ou plusieurs personnes de l'équipe ont bonne mémoire et sont sur le projet depuis suffisamment longtemps, peut-être qu'on donnera la véritable raison au nouvel arrivant. Mais dans la plupart des cas, j'ai bien peur que la réponse soit "Parce que nous avons toujours fait comme ça". Ce n'est pas une réponse que qui que ce soit veuille entendre.
Souvenez-vous que si vous obtenez une réponse comme celle-ci, vous avez toujours le choix. Vous pouvez continuer à faire les choses de la façon dont vous les avez toujours faites, car vous y êtes habitués, ou parce que c'est plus sécuritaire, puisque vous ne vous souvenez pas de pourquoi vous avez commencé à les faire de cette façon. Sinon, vous pouvez changer et espérer que vous avez pris en compte toutes les répercussions possibles. Après tout, que pourrait-il se passer de mal ? Eh bien, comme cela se profile... plein de choses. Par exemple :
- Vous pourriez prendre un chemin qui a déjà été exploré et rejeté, gaspillant les efforts et le temps du projet.
- Vous pourriez frustrer le client en faisant un changement qui va à l'encontre du fonctionnement du système dont le métier a besoin.
- Vous pourriez violer une contrainte de conformité atténuée par la façon dont vous faisiez cela, et vous placer, vous ou votre client, en difficulté juridique.
Toutes ces conséquences pourraient être évitées juste en prenant le temps de mettre les choses par écrit. Quand votre équipe prend une décision qui change votre façon de travailler, notez la date à laquelle la décision a été prise et la logique qui la soutient (si vous êtes bons, vous pourriez même avoir un processus de prise de décision qui produit des artéfacts auxquels vous pouvez référer). Ainsi, plus tard, quand quelqu'un demandera "Pourquoi faites-vous cela ou utilisez-vous cet outil ?", vous pourrez répondre à la question en toute confiance.
Préparer l'Automatisation d'un Processus Ennuyant
Les développeurs trouvent souvent des processus qu'ils veulent automatiser. Ce sont ceux qu'ils répètent régulièrement et qui font perdre du temps de développement précieux. Cependant, bien trop souvent, je tombe sur des processus manuels qui sont effectués peu fréquemment (peut-être une fois toutes les quelques semaines), et qui impliquent une série d'étapes à suivre dans un ordre précis. Si personne ne prend la peine de mettre ce processus par écrit, il y a de bonnes chances pour qu'il soit effectué de façon incorrecte ou que des étapes manquent, faisant perdre encore plus de temps. De plus, il n'y a, en pratique, aucune manière d'automatiser un processus sans l'avoir mis par écrit au préalable.
Si vous vous retrouvez à effectuer une tâche comprenant plusieurs étapes - et que vous avez une bonne chance d'avoir à refaire, notez ces étapes. Cela permettra d'économiser du temps à la prochaine personne qui aura à l'effectuer manuellement, et vous préparera pour le jour où vous serez enfin assez frustrés pour l'automatiser.
Couvrir vos arrières
Sur des projets Agile, comme le manifeste le décrit, on préfère la communication face à face. Ce type de communication est optimale pour les exigences, puisque toutes les informations peuvent être récoltées, qu'elles soient verbales ou non. Cependant, il y a des moments où ces informations peuvent être mal interprêtées, ou plus probable, mal rappelées. Cela peut se passer des deux côtés : les développeurs pourraient penser qu'ils ont entendu quelque chose que le client n'a pas dit, ou le client pourrait oublier (je vais partir du principe que cela arrive principalement involontairement) qu'il ou elle a dit aux développeurs de partir dans une certaine direction. Cela peut forcer les développeurs à devoir insister, plus tard, sur le fait qu'on leur a demandé de faire telle action, sans preuve que ce soit vrai ou faux. Dans ce cas, mon expérience a montré que le client gagne presque toujours, et le développeur repart frustré avec parfois le sentiment d'avoir été abusé.
Cela ne ressemble pas à ce que les développeurs voudraient qu'il se passe. Voyons, comment pourrions-nous éviter cette situation ? Je ne sais pas... peut-être que nous pourrions mettre les choses par écrit ? Tout ce que cela demanderait est un email de suivi, après la conversation téléphonique ou la réunion en face à face, qui décrirait avec les mots des développeurs ce qu'ils pensent qu'on leur demande de faire. Cela ne demande pas beaucoup d'efforts, et fournit un bon moyen de vérification plus tard, quand la question est de savoir pourquoi le système a été développé de cette façon.
Idées pour une Documentation Simple
Pour la plupart des gens, la documentation n'est pas naturelle, et carrément douloureuse pour la majorité des développeurs. Pourtant, comme illustré au-dessus, elle a de l'intérêt. Voici quelques idées pour la rendre moins à-se-taper-la-tête-contre-un-mur :
- Faites-la tout de suite. Beaucoup d'entre nous aiment procrastiner quand il s'agit de faire les choses que nous n'aimons pas faire. Ne faites pas cela avec ce type de documentation. C'est mieux quand c'est frais, et c'est plus simple quand vous n'avez pas à vous arrêter et vous souvenir. Juste après la conversation, trouvez un poste de travail ou un appareil mobile et écrivez un résumé.
- Trouvez de bons outils pour vous aider. En parlant d'appareils mobiles, il y a vraiment beaucoup de bons outils disponibles pour mettre les choses par écrit. Avant, nous devions aller chercher le bon endroit du wiki et utiliser des langages de balisage non-intuitifs pour documenter même les choses les plus simples. De nos jours, il y a les omniprésents Evernote et OneNote, et tant d'autres comme eux ; il y a des blogs et des microblogs (Twitter est-il hors de question pour votre projet ?) ; et si aucun d'eux ne fonctionne, il y a l'email. Trouvez votre favori.
- Gardez cela court. Vous n'avez pas besoin d'écrire une nouvelle pour documenter une discussion. Même si vous ne pouvez pas utiliser Twitter, faites en sorte d'être concis. Que pouvez-vous dire en 140 caractères qui soit suffisamment descriptif pour être utile, mais suffisamment court pour amener rapidemment au but ? La probabilité qu'un document soit lu plus d'une fois est inversement proportionnelle à sa taille.
- Mettez-le où vous pourrez le retrouver. Mettre les choses par écrit ne vous aide pas si vous ne retrouvez pas ce que vous avez écrit quand vous en avez besoin. Mettez-le à l'endroit où le trouver est le plus évident (e.g. dans un répertoire de documentation de projet déjà établi, au même endroit que là où vous mettez le code source, dans un email avec toute l'équipe en copie), et idéalement là où vous pouvez le chercher électroniquement. Ne l'écrivez pas juste sur le tableau de votre zone d'équipe (même si vous pourriez vouloir le faire en addition à le mettre quelque part pour le long terme). Vous pourriez essayer de le placer à plusieurs endroits et de voir où on le trouve... vous pourriez même collecter des métriques sur l'endroit où le contenu a été trouvé pour décider du meilleur endroit où le conserver ! Je sais, cela doit sonner comme le discours d'un fou pour certains.
Ce Doit Etre une Habitude
Comme je le disais, documenter ces petites occurrences dans la vie quotidienne de votre projet ne sera pas naturel ; vous allez devoir vous forcer. Je sais que vous préféreriez coder, mais forcez-vous à le faire ; je vous promets que ça vaut le coup. Si vous faites en sorte de sauter sur votre système de prise de notes quand quelque chose se passe, cela deviendra assez rapidemment une seconde nature. Puis, vous vous demanderez comment vous avez pu faire sans cela.
A propos de l'Auteur
Nate McKie est le co-fondateur et Directeur Technique d'Asynchrony, une entreprise de consulting à St. Louis, dans le Missouri. Nate a dirigé les efforts pour faire d'Asynchrony un des pratiquants-leadeurs des techniques et des idées Agile, et pour étendre les disciplines de qualité de code et d'implémentation rapide à travers sa base de clients commerciaux et gouvernementaux. Dans son rôle, Nate guide les aspects techniques de l'entreprise et enseigne les techniques Agile aux clients. Vous pouvez suivre Asynchrony sur Twitter via @asynchrony et Nate McKie via @natemckie.