Cartes, or et épices : pourquoi négliger la documentation peut faire échouer votre projet

Quel était le bien le plus précieux que les explorateurs d'autrefois rapportaient de leurs voyages ? De l'or et des épices ? Faux. Des cartes.

Christophe Colomb n'aurait jamais fait son célèbre voyage en 1492 sans un carte conçu par ses prédécesseurs. Un jeu d'espionnage pour obtenir des cartes portugaises a jeté les bases de la Compagnie néerlandaise des Indes orientales, sans doute la société la plus chère de l'histoire de l'humanité. À son apogée en 1637, elle valait 78 millions de florins néerlandais, soit l'équivalent de 7,9 billions de dollars en dollars de 2017. Cela représente plus de 10 000 milliards de dollars en 2024, soit plus que Microsoft , Nvidia et Apple combiné Les trésors palpables provenant de nouvelles terres étaient importants à court terme, mais à plus long terme, c'était la connaissance qui forgeait les véritables fortunes.

Comment se fait-il que dans le monde technologique d'aujourd'hui, nous ayons tendance à l'oublier ? En quête d'un succès immédiat, nous sommes souvent réticents à consacrer du temps et des ressources précieuses à la production et à la maintenance de la documentation technique. Pour parler en termes du XVIIe siècle, nous nous précipitons pour récupérer de l'or et des épices sans tracer nos cartes qui, à leur tour, auraient pu nous conduire à beaucoup plus d'or et d'épices. Êtes-vous sceptique ? Ohé, regardons cela de plus près...

Code farfelu

« Comme vous vous en souvenez sans doute, la stase hypnoïde des schémas neuronaux du cerveau peut être analysée par un faisceau extra-électromagnétique qui… » « Arrêtez ! » s’impatienta Ard Vark. « Que voulez-vous dire par « comme nous nous en souvenons sans doute ? » Comment pouvons-nous nous en souvenir alors que nous ne l’avons jamais su ? – Cette citation de Wacky World, une histoire d’un grand écrivain de science-fiction Edmond Hamilton, fait référence aux Martiens, pas aux programmeurs. Pourtant, de nombreuses personnes considèrent les développeurs comme s’ils venaient d’une autre planète – en particulier ceux qui n’ont qu’une vague idée du développement logiciel et de ses complexités. Le fait est que les développeurs supposent souvent que les autres connaissent le code aussi bien qu’eux et considèrent souvent la documentation technique inutile. Cet état d’esprit risque de rendre le projet aussi complexe et incompréhensible pour les étrangers qu’une « stase hypnoïde », mettant en péril à terme le succès potentiel du projet.

La réticence à créer de la documentation est souvent due aux mêmes raisons que celles qui poussent les gens à procrastiner dans d’autres domaines : cela nécessite un investissement important en temps et en argent. En d’autres termes, c’est souvent dû à la paresse pure et simple et au désir d’économiser de l’argent, deux obstacles difficiles à surmonter. Cependant, la documentation n’est pas seulement une information redondante qui semble évidente pour tout le monde ; elle contient des détails critiques qui peuvent être indispensables. Souvent, l’absence de documentation complique considérablement la détection et la correction des erreurs, rend la maintenance et les mises à jour plus difficiles et augmente le temps nécessaire à l’intégration des nouveaux membres de l’équipe. Alors que les équipes sans documentation sont contraintes d’effectuer des tâches répétitives, les projets avec une documentation bien structurée font preuve d’une grande efficacité et d’une grande fiabilité – c’est un fait, pas une simple opinion.

Certes, certains programmeurs prétendent que le code qu'ils écrivent est si clair et compréhensible que la documentation est tout simplement inutile. Cependant, en réalité, même le code le plus parfait peut être déroutant pour les autres ou perdre de sa clarté au fil du temps. Ce qui semble clair aujourd'hui peut devenir un casse-tête demain. Par exemple, pourriez-vous facilement gérer une simple carte perforée des années 70 ?

Bus factor, Burnout et autres bêtes fantastiques

La théorie est bonne, mais la pratique est plus convaincante. Voici quelques exemples, basés sur des faits réels, dont seuls les noms de personnes et d'entreprises sont fictifs. Ces brèves études de cas couvrent les problèmes les plus courants qui surviennent en raison de mauvaises pratiques de documentation technique.

Histoire n°1 : Incapacité à évoluer

Le projet « NoDocumentationPlease », une start-up de streaming vidéo à succès à l'origine, a rencontré de sérieux problèmes lors de son expansion en raison d'une documentation technique insuffisante. Lorsque l'équipe a dû s'agrandir, les nouveaux employés n'ont pas pu comprendre pleinement leurs tâches et personne n'a pu leur fournir d'explications adéquates. Sans soutien ni formation appropriés, les nouvelles recrues ont rapidement quitté l'entreprise. Cela a non seulement ralenti la progression du projet, mais a également entraîné la perte de talents clés, mettant en péril l'efficacité globale et l'avenir du projet. En conséquence, les streamers ont quitté le chat et le projet a été arrêté.

Histoire n°2 : Problèmes de maintenance

L'entreprise « IKnowEverything » a développé une plateforme cloud pour la synchronisation et le stockage de données. Au début, le projet a progressé rapidement, mais au fil du temps, ses développeurs ont eu du mal à maintenir et à mettre à jour la plateforme en raison du manque de documentation technique claire et à jour. Cela a entraîné un développement plus lent, davantage de bugs et des clients insatisfaits. Finalement, l'entreprise a commencé à perdre ses anciens clients, et les nouveaux clients ont choisi des concurrents avec des solutions plus stables et plus fiables. Les revenus ont considérablement diminué tandis que le coût de la maintenance inefficace a augmenté. Une documentation appropriée des aspects techniques dès le départ aurait pu leur permettre de se développer avec succès. Cependant, cela n'a pas été fait à temps. Par conséquent, l'entreprise n'a pas pu surmonter les défis techniques et financiers et a dû fermer.

Histoire n°3 : L'épuisement professionnel des développeurs

Le projet « SmartestEver » a rencontré de graves problèmes car son développeur principal, Andrew, qui s'occupait de presque tout, a démissionné après avoir été submergé par les nombreuses questions de l'équipe. Si « SmartestEver » avait eu une documentation appropriée, les développeurs juniors auraient pu facilement se référer à la FAQ et résoudre les problèmes courants. Au lieu de cela, ils ont bombardé Andrew de questions, et sans lui et la documentation nécessaire, l'équipe n'a tout simplement pas pu continuer et le projet a été arrêté (appuyez sur F pour Andrew).

Histoire n°4 : Le facteur bus

Dans la société « NoDocsNeeded », un logiciel prometteur était développé par John, un développeur clé qui détenait toutes les connaissances mais ne s'était pas donné la peine de les documenter. Ses responsables n'ont pas non plus pris la peine de le convaincre. Un jour, John est parti en voyage d'affaires et n'est jamais revenu. Sans documentation ni compréhension de l'architecture et de la logique du produit, les autres membres de l'équipe n'ont pratiquement rien pu faire. Le projet a été gelé et l'argent investi a été gaspillé. La leçon est simple : la documentation et la diffusion des connaissances au sein d'une équipe sont cruciales pour éviter de dépendre d'une seule personne. D'ailleurs, ils recherchent toujours John...

Histoire n°5 : Aucun prophète n'est le bienvenu chez Open Source

Maria a créé sa première bibliothèque open source mais n'a pas rédigé de documentation pour celle-ci. Personne ne comprenait ce que faisait cette bibliothèque et Maria a décidé qu'elle n'écrirait plus de bibliothèques car cela lui semblait inutile. Le projet de Maria s'est terminé avant même d'avoir commencé et elle a décidé de changer de métier.

De mousse à capitaine

Ok, nous avons un peu de théorie et de pratique, plongeons maintenant dans la recherche et les statistiques. Enquête sur les développeurs Stack Overflow 2024 États 84 % des personnes interrogées utilisent la documentation technique pour comprendre les fonctionnalités des technologies. Cependant, même avec la documentation, ils ne parviennent souvent pas à trouver les réponses dont ils ont besoin, comme le montrent les ressources les plus populaires suivantes : Stack Overflow (80 %), tutoriels écrits (68 %), blogs (61 %) et vidéos explicatives (54 %). Microsoft Research : La vie quotidienne des développeurs de logiciels trouvé En moyenne, les développeurs consacrent 1 à 2 % de leur journée (8 à 10 minutes) à la documentation, et 10,3 % des développeurs déclarent qu'une documentation obsolète les oblige à passer trop de temps à chercher des réponses par eux-mêmes. La nécessité de la documentation est également une préoccupation majeure pour la communauté universitaire. Une simple recherche sur Google Scholar pour <"documentation" ET "logiciel"> rendements plus de 4 millions de résultats, ce qui indique clairement un grand nombre de publications scientifiques traitant du sujet.

Les principales conclusions sont étonnamment simples : n°1 – Tout le monde a besoin de documentation pour comprendre la technologie et/ou le travail des autres ; mais n°2 – Peu de gens prennent la peine de la rédiger et de la maintenir ; et par conséquent n°3 – Une grande partie de la documentation est mal rédigée, obsolète et généralement inutile. Alors que faut-il faire ? Changer sa motivation à tous les niveaux.

Un groupe de chercheurs de l'Université des sciences appliquées HAN et de l'Université de Groningue (toutes deux aux Pays-Bas) identifié les problèmes les plus courants avec la documentation technique :

• La documentation informelle souvent utilisée par les développeurs est difficile à comprendre ;

• La documentation est considérée comme un gaspillage lorsqu’elle ne contribue pas immédiatement au produit final ;

• La productivité du développeur se mesure uniquement par la quantité de logiciels fonctionnels ;

• La documentation n’est souvent pas synchronisée avec le logiciel réel ;

• Les développeurs ont souvent une vision à court terme, en particulier dans les environnements de développement logiciel continu.

  
  

Cela vous semble-t-il familier ? Je suis sûr que la plupart d'entre nous avons rencontré la plupart de ces problèmes, voire tous, au cours de notre travail quotidien. Et cela ne se résume pas seulement à la procrastination ou au manque de ressources. Certains de ces problèmes proviennent d'un manque de gestion adéquate, de planification à long terme et, en fin de compte, de vision stratégique. Et c'est là que vient la partie difficile, car ce n'est pas seulement à nous, les développeurs, de les résoudre. Certains problèmes doivent être traités par les managers, les parties prenantes du produit ou même les propriétaires de l'entreprise. C'est pourquoi il est essentiel qu'une vision appropriée des aspects techniques ne soit pas seulement un accessoire agréable, mais fasse partie des valeurs fondamentales de l'entreprise dans son ensemble, partagées par tous, des fondateurs aux développeurs juniors.