L’article d’Ugo Dimini explore l’importance de la documentation comme actif stratégique, tout en dénonçant ses dérives. Il critique notamment le "théâtre de la documentation", où des équipes produisent des documents superflus ou obsolètes, comme des docstrings génériques ou des README surchargés, qui alourdissent sans apporter de valeur. L’auteur illustre ce problème avec l’exemple d’un README de 500 lignes inutilisable, car non mis à jour et incapable de permettre le lancement d’un projet.
Il souligne que la documentation pertinente doit se concentrer sur l’asymétrie de la connaissance : expliquer le pourquoi plutôt que le comment, ce que le code ne peut pas transmettre. Une documentation efficace réduit la charge cognitive en clarifiant les intentions, les limites et les décisions stratégiques, comme les problèmes clients résolus ou les choix techniques abandonnés.
Enfin, Dimini propose un cadre de décision basé sur le retour sur investissement (ROI) pour évaluer la documentation. Il distingue notamment la documentation fonctionnelle, qui décrit le problème et la vision à long terme, comme un actif à ROI infini, car elle aligne les équipes techniques, produit et marketing et évite les dérives futures.
L'article souligne l'importance de tester les instructions de son README comme le ferait un utilisateur. L'auteur recommande de suivre les étapes du README sur une machine virtuelle fraîchement installée pour identifier et corriger les problèmes de dépendances ou de configurations manquantes. Cela permet d'éviter des tickets d'erreurs répétitifs et de rendre le processus d'installation plus fluide pour les utilisateurs finaux. Une approche simple mais efficace pour améliorer l'expérience utilisateur de vos projets.
De bons conseils pour l'écriture de README
Tout est dans le titre