Le pouvoir surprenant de la documentation

Par Vadim Kravcenko

Le pouvoir surprenant de la documentation, par Vadim Kravcenko

Je suis un grand fan de documentation. Je pense que c'est la chose la plus ennuyeuse à faire après le codage. Elle apporte à l'entreprise une telle valeur à long terme que chaque heure investie dans la documentation par qui que ce soit permet d'économiser littéralement x100 heures de productivité dans toute l'entreprise.

Si vous êtes directeur technique, la documentation est votre arme secrète, le héros méconnu de votre startup, le chevalier gris qui fait avancer les choses derrière le développement du produit. Elle élimine les conjectures et la réinvention de la roue. Considérez-le comme votre ticket d'or pour un onboarding super rapide. Cette carte au trésor guide les nouveaux venus et les vétérans des autres départements dans le labyrinthe des processus de votre startup. Votre équipe trouvera ses marques plus rapidement, deviendra plus vite un contributeur efficace et travaillera plus efficacement que vous ne le pensez, tout cela parce que vous avez décidé de donner la priorité à l'écriture.


Voici une question pour vous : qu'est-ce qui est le mieux ?

1. Écrire un courriel à quelqu'un, le faire sortir de sa zone de concentration, lui demander d'expliquer le fonctionnement d'un logiciel
2. Ou rechercher vous-même les informations nécessaires et les traiter à votre propre rythme.

Indice : c'est la deuxième solution.

Importance de la documentation

Commençons par les bases.

Imaginez que vous êtes cofondateur technique d'une startup en phase de démarrage (ou peut-être n'avez-vous même pas besoin d'imaginer), et que vous êtes noyé dans le chaos, comme on peut s'y attendre. Vous jouez au chat et à la souris tous les jours et vous essayez juste de retrouver un peu de lucidité avant d'être entraîné dans un nouveau problème. Comment sortir de cette spirale ? La réponse est simple : la documentation. Je ne parle pas ici de la rédaction d'un simple manuel pratique ou de la consignation des comptes rendus de réunions ; ces éléments sont également importants, oui, mais je veux parler de l'instauration d'une culture où le savoir n'est pas confiné à des individus, mais dispersé et accessible à l'ensemble de l'organisation.

Chaque chose qui n'est pas consignée par écrit équivaut à un gaspillage de ressources à l'avenir et à un risque de maux de tête. Vos maux de tête. Et je ne sais pas ce qu'il en est pour vous, mais j'aimerais m'assurer que je n'ai pas de maux de tête ; c'est pourquoi j'aime construire des systèmes qui fonctionnent sans moi. Imaginez maintenant la quantité de choses que vous n'avez pas encore écrites, et c'est votre potentiel actuel de vous noyer dans des problèmes inattendus. Par exemple, votre déploiement continu s'est interrompu à cause de certaines mises à jour de paquets. Par coïncidence, seul Bob du département X sait comment résoudre ce problème. Oh, et il est en vacances toute la semaine.

Vous pouvez considérer la documentation comme l'épine dorsale d'un partage efficace des connaissances. Dans les premières phases d'une startup, lorsque vous êtes le seul à coder et à construire, le partage d'informations et de connaissances peut être aussi simple qu'une conversation avec votre PDG de l'autre côté du bureau. Vous avez les connaissances et les moyens de réparer quelque chose en cas de panne. Mais c'est épuisant et vous êtes en quelque sorte le facteur limitant de l'entreprise. Si vous partez en vacances, vous ne partirez pas en vacances parce que tout s'arrêtera si vous partez.

Au fur et à mesure que la startup prend de l'ampleur, le nombre de personnes, de projets et la complexité augmentent de manière exponentielle. Les connaissances sont cloisonnées dans votre tête, la communication devient alambiquée et, avant que vous ne vous en rendiez compte, les gens passent plus de temps à vous chercher des informations qu'à les utiliser. Si vous êtes un cofondateur technique, extrayez toutes les connaissances que vous pouvez et mettez-les par écrit. Cela servira de source universelle de vérité, de dépôt dynamique qui capture et préserve la sagesse collective. Cette sagesse peut aider tous les membres de l'équipe à résoudre des problèmes dont ils n'avaient aucune idée il y a une minute. Cela vous permettra également de prendre des vacances. Croyez-moi, vous en avez besoin.

La documentation d'abord, les réunions ensuite

Maintenant que vous savez que la documentation vous rend la vie plus facile et non plus difficile, parlons du temps et de l'efficacité.

Dans le monde des startups, le temps est la monnaie ultime. Chaque tic-tac de l'horloge porte le poids des décisions prises, des produits construits et des marchés conquis. Et les réunions sont des voleurs notoires de cette monnaie. Ne vous méprenez pas. Je ne dis pas que toutes les réunions sont mauvaises, mais nous devons examiner de près leur coût par rapport à leur valeur. Pour reprendre les mots de Bukowski, « Ne le faites pas à moins que cela ne sorte de votre âme comme une fusée », appliquez le même principe aux réunions - ne les organisez pas à moins qu'elles ne soient nécessaires.

Le besoin constant d'organiser des réunions est le symptôme d'un problème plus profond : un manque de documentation claire, accessible et fiable. Un flux de travail bien documenté ne nécessite pas une séance d'une heure pour obtenir des éclaircissements. Une décision bien documentée n'a pas besoin d'une salle pleine de gens pour comprendre sa raison d'être. Une base de connaissances bien documentée n'a pas besoin d'une réunion de groupe chaque fois qu'un nouveau membre rejoint l'équipe.

"Mais les réunions ne sont-elles pas essentielles à la communication ?" Oui, elles le sont. Mais un trop grand nombre d'entre elles, en particulier celles qui sont mal gérées, peuvent paralyser votre startup. Elles créent une illusion de productivité, alors qu'en réalité, elles la freinent. En réduisant la dépendance aux réunions et en mettant l'accent sur la communication asynchrone axée sur la documentation, vous donnez à votre équipe les moyens de communiquer efficacement sans être limitée par les limites d'un appel Zoom.


Pensez-y : chaque réunion inutile est une occasion manquée. C'est du temps qui aurait pu être consacré à affiner cet algorithme crucial ou simplement à prendre un moment pour se ressourcer et éviter l'épuisement professionnel. Par essence, réduire la dépendance à l'égard des réunions ne consiste pas seulement à récupérer du temps, mais aussi à retrouver la capacité de se concentrer, d'innover et de créer, ce qui est l'essence même d'une startup.

En tant que directeur technique ayant traversé le creuset ardent de la croissance d'une startup plus souvent qu'à son tour, je peux vous assurer que votre temps et vos ressources sont mieux utilisés à documenter qu'à organiser des réunions. La plupart des réunions pourraient facilement être remplacées par un document bien rédigé qui présente les données pertinentes et les solutions proposées et qui invite à réagir.

Par ailleurs, les réunions favorisent souvent les voix les plus fortes, et pas nécessairement celles qui ont les meilleures idées. Il s'agit d'une forme subtile de partialité qui peut étouffer l'innovation et la diversité de pensée. La documentation, en revanche, met tout le monde sur un pied d'égalité. Elle offre à chaque membre de l'équipe une plateforme pour exprimer ses pensées et ses idées, quel que soit son rang ou son style de communication. Elle favorise une culture de la pensée et de la réflexion plutôt que des jugements à l'emporte-pièce et des décisions impulsives.

Vous pensez peut-être que c'est une bonne idée d'organiser une réunion à l'échelle de l'entreprise pour annoncer que vous allez intégrer l'IA dans tous les processus dès maintenant. Mais est-ce bien le cas ? Dans la poussée d'adrénaline que provoque le fait de faire partie d'une startup au rythme effréné, il est facile pour les détails de se perdre dans le tourbillon. Vous mentionnez quelque chose, vous faites une blague, vous marmonnez et communiquez mal, et avant même de vous en rendre compte, vous avez un autre problème à résoudre. Mettre par écrit la décision et la manière dont elle a été prise permet d'y voir plus clair.

Chaque décision est une brique dans les fondations de votre startup en pleine croissance, et les documenter peut fournir un dossier solide, une sorte de plan d'architecture qui détaille vos processus de pensée, vos préoccupations et votre raisonnement. Cette clarté peut s'avérer inestimable à mesure que vous évoluez et que vous êtes confronté à des défis de plus en plus complexes.

Lorsque vous introduisez la documentation dans votre processus de prise de décision, elle agit comme un référentiel de connaissances. Elle contient le contexte, les idées et les enseignements qui accompagnent chaque décision. Et ce référentiel peut être consulté lorsque des situations similaires se présentent. Vous pouvez y faire référence. En soi, il s'agit d'une astuce en matière de durabilité.

En tant que directeur technique, comment pouvez-vous faciliter cette démarche ? Encouragez votre équipe à documenter son processus de prise de décision afin de clarifier les hypothèses, le raisonnement et les résultats attendus. Faites de la discussion de ces décisions documentées une pratique courante lors de vos réunions, afin de promouvoir une culture de retour d'information ouvert et de prise de décision collaborative.

L'avantage de cette méthode est qu'elle transforme chaque décision en une opportunité d'apprentissage, favorisant ainsi un état d'esprit de croissance au sein de votre équipe. Elle permet à chacun de voir les conséquences de ses choix passés et de comprendre les considérations qui les sous-tendent, ce qui le rend plus apte à prendre des décisions.

Construire une culture "documentation-first"

La culture "documentation-first" implique de cultiver une conscience commune dans votre startup, une force unificatrice qui relie tout le monde. Il ne s'agit pas seulement d'une adhésion rigide à un processus, mais aussi de démocratiser le savoir, d'abattre les barrières hiérarchiques et de favoriser une culture de l'apprentissage. Une culture axée sur la documentation ne signifie pas que tout le monde est occupé à rédiger des documents toute la journée. Elle signifie que chacun apprécie la valeur de la documentation et du partage de ses expériences.

Cela signifie aussi, bien sûr, que lors de l'élaboration d'un projet, il faut toujours tenir compte de la documentation dans le cadre de TOUTE tâche. Le fait qu'un certain pourcentage du temps des employés soit consacré à l'écriture de leurs histoires devrait être un principe de base. Il ne s'agit pas seulement d'efficacité - il s'agit de créer un environnement où le partage des connaissances est célébré. Il s'agit de créer une culture qui ne se contente pas de créer un produit, mais qui élabore une histoire - une histoire de croissance collective.


Vous pouvez jouer un rôle de catalyseur et de facilitateur. Commencez toujours par donner l'exemple. Documentez vos propres processus et décisions et partagez-les ouvertement. Prenez toujours des notes. Encouragez une culture du retour d'information et de l'apprentissage, où chaque document est un point de départ pour la discussion, l'amélioration et l'innovation. Si une décision doit être prise, commencez par un document, pas par une réunion. S'il y a une discussion pour/contre, commencez par un document.

En encourageant vos collègues à documenter leurs processus, leurs décisions et leurs apprentissages, vous montrez que vous appréciez leurs idées et leurs expériences. Cela favorise un sentiment d'appropriation et d'engagement au-delà des rôles et des tâches qui leur sont assignés. Ils deviennent des contributeurs actifs à la base de connaissances de l'entreprise et à son succès.

Félicitez ceux qui rédigent une bonne documentation. Partagez-les publiquement. Félicitez ceux qui sont aussi enthousiastes que vous à l'égard de la documentation.

Les outils

Ensuite, donnez aux membres de votre équipe des outils qui facilitent la documentation. Trouvez un outil qui corresponde aux besoins et aux flux de travail de votre équipe, qu'il s'agisse d'un disque partagé, de Notion, de Confluence, de Gitlab ou d'une autre plateforme de gestion des connaissances. Il en existe des centaines. N'oubliez pas que plus vous facilitez la tâche de votre équipe pour documenter son travail, plus elle sera encline à le faire.

Préparez des modèles ET des lignes directrices. Considérez-les comme l'ADN de votre documentation - ils fournissent la structure, la cohérence et la prévisibilité qui permettent à vos connaissances de se reproduire et de se répandre efficacement dans l'ensemble de l'organisation. Il s'agit d'une tâche complexe qui demande beaucoup de temps, mais une fois qu'elle est accomplie, tout devient plus facile.


Les modèles garantissent que les informations sont enregistrées dans un format standardisé, ce qui facilite leur compréhension et leur comparaison. Les lignes directrices, quant à elles, fournissent les « règles du jeu », garantissant que tout le monde comprend ce qu'il faut documenter, comment le faire et où le trouver.

Faites en sorte que la documentation fasse partie intégrante des valeurs de votre entreprise. Encouragez votre équipe à la considérer non pas comme une corvée supplémentaire, mais comme une partie intégrante de leur travail, aussi vitale que l'écriture du code. Faites-en une partie intégrante des évaluations de performance et des sessions de retour d'information. Demandez-leur de l'améliorer, et demandez-leur de trouver des failles dans vos processus.

Au fur et à mesure que votre startup évolue, ses besoins en matière de documentation évoluent également.

Le personnel

Désigner une équipe ou une personne dédiée à la documentation dans une startup en phase de démarrage peut sembler extravagant. Mais croyez-moi, c'est l'un des investissements les plus judicieux que vous puissiez faire. Pourquoi ? Parce que la connaissance est l'élément vital de votre startup, et qu'une équipe dédiée au manuel agit comme le système circulatoire, en veillant à ce que cette connaissance vitale circule librement et efficacement dans l'ensemble de l'organisation.

Les avantages vont au-delà de la simple gestion des connaissances. Votre équipe de documentation peut améliorer l'efficacité globale de l'organisation en comblant les lacunes entre les équipes, en facilitant la collaboration interfonctionnelle et en supprimant les cloisonnements. Elle sert de ciment à tous les cerveaux de l'équipe.

Le retour de bâton

Tout le monde ne va pas apprécier. Si vous êtes une startup établie avec quelques années d'expérience, il y aura des réactions négatives. N'oubliez pas que vous n'avez pas seulement affaire à du code, mais aussi à des personnes. Leurs craintes, leurs zones de confort et leurs hésitations sont aussi réelles que n'importe quel bogue technique. Ils doivent être traités avec le même degré de patience.

L'un des moyens les plus efficaces de faire face à la résistance est l'engagement. Écoutez les préoccupations de votre équipe, comprenez leurs points de vue et répondez à leurs craintes. Montrez-leur les avantages, l'efficacité et la libération qu'une culture de la documentation peut apporter. Et je tiens à le répéter : modélisez le comportement que vous voulez voir, soyez le premier à documenter, à partager, à apprendre, et montrez-leur à quel point cela peut être génial.


Célébrez ceux qui adoptent cette culture - leurs victoires, leurs efforts et leurs avancées vers une approche centrée sur la documentation. Non seulement cela les encourage, mais cela incite également les autres à faire de même.

Le seul problème n'est pas que « ça ne plaira pas à tout le monde ». La documentation elle-même ne sera pas non plus parfaite et pourrait être assez mauvaise au début. Ce n'est pas grave, ne paniquez pas. N'oubliez pas qu'il s'agit d'un organisme vivant qui a besoin de temps pour évoluer. En tant que directeur technique, votre rôle est de veiller à ce que la qualité de votre documentation s'améliore au fil du temps. Il ne s'agit pas de faire la police. Il s'agit de la cultiver.

Ce qui est bien

Il s'agit davantage de mes réflexions subjectives sur ce à quoi ressemble une bonne documentation.

Tout d'abord, la clarté et la concision. Il s'agit de décomposer des concepts complexes en éléments digestes, d'éliminer le gras et de se concentrer sur l'essentiel. Votre document n'est pas un roman interminable ; c'est un guide que les autres doivent suivre.

• Par exemple, dans Notion, vous pouvez mettre l'accent sur les informations de différentes manières.
• Si elles vous semblent trop arides, elles doivent être réécrites.
• Ajoutez des illustrations et des explications vidéo.

Viennent ensuite la structure et l'organisation. Vous avez besoin d'un format qui ait du sens, qui soit intuitif. Si les gens ne peuvent pas trouver ce qu'ils cherchent, ils se perdront et seront frustrés. Votre document doit les guider, pas les embrouiller.

• Décomposez-le en pages et créez des liens entre les documents connexes.
• Créez une table des matières.
• Suivant / Précédent - suggérez quel autre document pourrait être utile.

Ensuite, l'accessibilité et la facilité de découverte. Votre document n'est pas un tome secret caché dans une vieille bibliothèque poussiéreuse. Il s'agit d'une ressource vivante qui doit être facilement accessible et découvrable.

• Utilisez des étiquettes et des catégories, et segmentez vos informations en différents groupes.
• Utilisez la recherche en texte intégral ou la recherche vectorielle par IA

Enfin, et c'est essentiel, votre document n'est pas un monument. Ce n'est pas quelque chose que l'on construit une fois et que l'on oublie. Il s'agit d'une entité en croissance et en évolution qui nécessite des mises à jour et une maintenance régulières. Votre organisation change, vos connaissances se développent, et votre document doit en tenir compte.

• Suivez les dates des dernières modifications et mettez à jour celles qui remontent à plus d'un an.
• Déterminez qui est le propriétaire de ces informations et mettez-les à jour régulièrement.

Voici quelques systèmes de documentation open-source que je recommande d'étudier pour s'en inspirer :

• Basecamp - un manuel de l'employé joliment rédigé
• Gitlab - Le manuel de Gitlab est une documentation de 2000 pages dont les versions sont contrôlées et qui est constamment mise à jour. Il est fortement recommandé de le lire.
• Strapi - Inspiré par la transparence radicale de Gitlab, il s'agit également d'une bonne documentation à lire.
• Remote.com - Un autre bon exemple

Pas une solution miracle

Cela fait un moment que je chante les louanges de la documentation ; merci d'ailleurs d'avoir lu jusqu'ici. Mais laissez-moi poser mes pompons une minute : La documentation, bien qu'impressionnante, n'est pas une panacée magique. Elle n'arrivera pas comme un super-héros et ne sauvera pas votre startup de tous les problèmes. C'est un outil ; comme tout outil, il a ses limites. Vous serez toujours confronté à des problèmes... mais moins.

La documentation, bien qu'elle soit un atout pour la collaboration, ne remplace pas l'interaction humaine. Elle ne peut pas reproduire les nuances d'une communication en face à face, la valeur d'un retour d'information immédiat ou les liens qui se tissent lorsqu'une équipe se réunit pour s'attaquer à un problème délicat. La camaraderie qui s'instaure lors de ces réunions ou même lors de rencontres informelles est essentielle pour favoriser une culture de travail saine et stimuler la motivation de l'équipe. Si vous remplacez toute interaction humaine par une série de documents, vous préparez votre équipe à l'isolement et à la déconnexion, ce qui est un aller simple pour un faible engagement.

Le processus de documentation lui-même peut prendre beaucoup de temps. La rédaction d'un document pratique, concis et facilement assimilable relève d'un certain art. Cela demande de la réflexion, de la clarté d'esprit et un don pour la simplification. Certains diront que le temps passé à rédiger ces documents pourrait être mieux utilisé ailleurs. Et ils n'ont pas tout à fait tort. Si vous documentez chaque petit détail, vous disposerez d'une bibliothèque d'informations écrasante, aussi difficile à parcourir qu'une jungle dense, et qui ne sera peut-être pas si utile que cela.

Enfin, malgré tous vos efforts, la documentation peut rapidement devenir obsolète. La technologie évolue, les processus changent et ce qui était pertinent il y a un mois ne l'est peut-être plus aujourd'hui. Maintenir votre documentation à jour exige une vigilance constante et une maintenance régulière, ce qui peut s'avérer difficile pour une startup en pleine croissance et aux ressources limitées.

Conclusion

Mon conseil à tous les jeunes passionnés de technologie, aux futurs responsables de l'ingénierie et aux directeurs techniques est simple : cultivez l'amour de la documentation. Vous pouvez la considérer comme une corvée, une réflexion après coup ou une nuisance. Mais croyez-moi quand je vous dis ceci : La documentation n'est pas seulement une tâche sur votre liste de choses à faire ; c'est un pilier de la réussite et un pont qui relie les idées, les personnes et la vision. Ne la considérez pas comme un fardeau, mais comme une occasion d'apprendre, de partager et d'avoir un impact.

Commencez modestement, mais dès aujourd'hui. N'attendez pas une grande stratégie ou un outil parfait. Commencez par documenter votre code, vos décisions et vos apprentissages. Intégrez cela à votre flux de travail quotidien, et non à une corvée de fin de journée. Et au fur et à mesure que vous progressez, imprégnez vos équipes, vos projets et votre organisation de cette culture de la documentation. Créez des systèmes et des processus qui encouragent et facilitent la documentation.

S'il y a une chose que vous pouvez retenir de cet article, gardez ce mantra avec vous : « Documenter pour se donner les moyens d'agir, documenter pour grandir ». Adoptez cette philosophie et vous serez surpris des transformations qu'elle entraîne, non seulement dans votre carrière, mais aussi dans votre façon de voir et de naviguer dans le monde de la technologie.

Source : Healthy Documentation

Et vous ?

Pensez-vous que ces affirmations sont crédibles ou pertinentes ?
Quel est votre avis sur le sujet ?

Voir aussi :

Comment je livre des projets informatiques dans de grandes entreprises technologiques, par Sean Goedecke

Développement de logiciels à long terme, par Bert Hubert

Le Manifeste anti-héritage : Écrire du code qui dure, par Mensur Durakovic