Tout ce qui concerne la documentation logicielle est difficile, de l’allocation de temps pour le faire à sa mise à jour. Le succès de la documentation est difficile à atteindre et souvent il n’y a pas assez de temps pour mesurer l’impact. C’est parce qu’ils n’ont pas d’impact tangible sur l’expérience de l’utilisateur final. Nous sommes incapables d’accorder de la valeur à une excellente documentation. Pour cette raison, il n’est pas rare que les efforts pour créer et maintenir une documentation attrayante dépassent l’investissement en temps et une planification appropriée.
penny ou centime
Les développeurs de logiciels s’occupent d’écrire du code et du contenu (enfin la plupart d’entre nous ????). Nous pouvons facilement justifier nos salaires par rapport aux rôles que nous proposons et aux revenus qu’ils génèrent. Ainsi, lorsqu’il s’agit d’écrire et d’éduquer nos pairs sur ces fonctionnalités afin qu’ils soient mieux à même d’interagir avec votre code, nous remettons souvent en question la valeur de ces minutes par rapport à la livraison de la fonctionnalité suivante ou à la correction de ce vilain bogue sur place. Il y a tellement de dette technique, alors pourquoi écrivons-nous sur le code que nous devons refactoriser ?
Nous économisons ces minutes immédiatement, c’est un choix évident. Retour au code. Et nous économisons quelques centimes de temps. Avancez un peu; un collègue doit intervenir et mettre en œuvre un changement. Vous êtes absent (en train de travailler sur le prochain gros projet, en réunion, en vacances, ou peut-être avez-vous quitté l’entreprise !) et il n’y a pas de documents. Ces centimes commencent à produire des intérêts maintenant. Heureusement, il y a quelques commentaires dans le code. Bon à savoir src signifie en réalité sourceOui function sort(a, b) prendre deux entiers. Mais le raisonnement n’est pas vraiment là, alors continuons à creuser. La demande d’extraction n’a pas de description, git blame cela n’aide pas car qui a écrit le code n’est pas présent. Je suppose qu’il est temps de jouer au détective et à l’ingénieur inverse. Ces centimes sont des centimes maintenant. Décrire a beaucoup moins de surcharge cognitive que l’investigation. Par conséquent, le coût de développement de notre application augmente avec le temps du développeur, tâche par tâche.
La documentation est une tâche d’hygiène. Nous le faisons pour garder les choses bien rangées, confortables et ergonomiques. Ils sont un catalyseur direct de l’expérience du développeur, pour le meilleur ou pour le pire. Et l’expérience de développement détermine la concentration que les développeurs peuvent mettre sur le code qui compte vraiment au lieu de se frayer un chemin à travers les sous-bois.
Brosser les dents
J’espère que nous pouvons tous convenir que se brosser les dents est une chose importante à faire tous les jours. Ce n’est pas le genre d’habitude qu’on peut prendre tout le vendredi et rattraper les jours sautés. Et dans ce cas, la documentation est quelque chose de similaire. Bien sûr, nous pouvons tout écrire d’ici la fin du trimestre, mais ce sera beaucoup plus difficile et beaucoup plus long. Par exemple : vous souvenez-vous de ce que (ou pourquoi) vous avez codé il y a trois mois ?
La surcharge cognitive liée à la documentation des choses augmente à partir du moment où vous expédiez le code. Idéalement, la documentation est comme écrire des tests (ce que nous faisons tous !), et chaque fois que nous changeons quelque chose, nous mettons à jour les documents.
Enlever les obstacles
Malheureusement, la plupart d’entre nous n’ont pas l’habitude d’écrire de la documentation ; en effet, le flux de travail est souvent semé d’embûches. Nous avons terminé le code, fermé le fichier (ou l’IDE, ou le projet) et sauté dans un éditeur Markdown (ou Jira, ou Wiki, etc.), et maintenant nous devons trouver le bon endroit pour mettre les connaissances que vous venez de créé. , soumettez-le pour examen ; d’autres nous diront si nous avons choisi le meilleur endroit, si nous l’avons écrit assez clairement, etc. En attendant, le code ne peut pas attendre – nos utilisateurs bénéficient déjà de cette nouvelle fonctionnalité brillante. (Si c’est vous, dur ! J’y suis allé, j’ai fait ça. Vous avez ma sympathie.)
Le processus a des processus, les décisions s’ouvrent en questions. Et oui, la pratique rend parfait, mais idéalement, nous n’aurions pas besoin de passer autant de temps (et d’énergie !) à mener une diligence raisonnable. Cette friction nous fait mal quand il s’agit de rester dans l’habitude, et le temps que nous passons à trouver l’endroit où mettre le code a épuisé notre motivation.
Connecter les pièces mobiles
Comme d’habitude, la solution du développeur à un problème de friction est automatisation. Évitez les travaux fastidieux et répétitifs en en faisant des produits dérivés. Swimm accomplit cela en prenant certaines de ces nombreuses décisions pour vous dans ce qu’ils appellent un « écosystème de documentation », qui porte bien son nom.
- Où mettre la documentation ? Juste là, avec le code.
- Quand rédiger la documentation ? Au fur et à mesure que vous l’implémentez. Ou lorsque vous ouvrez le PR (au plus tard !).
En bref, vous écrivez une méthode ; vous expliquez la méthode sur-le-champ. La partie « magique » vient quand, parce qu’ils sont co-localisés, il est possible de documenter directement les paramètres et les variables Dans le code au texte dans les documents. Ainsi, lorsque le code change, la documentation sait qu’il est désormais obsolète et peut alerter toute votre équipe à ce sujet.
Toute cette automatisation soignée nécessite un peu de configuration et éventuellement quelques modifications de vos interfaces de codage et des processus associés.
Code des actes
Si vous utilisez VS Code ou l’un des IDE JetBrains, il est possible d’avoir une extension/plugin intégré. Une fois que vous avez écrit le code, une « vague de nage » apparaîtra à côté du code déjà documenté, vous pouvez donc suivre le lien et modifier le code dans un éditeur Markdown amélioré. Cet éditeur a une auto-complétion intéressante inspectée à partir de votre code (commencez à taper un nom de variable et vous le verrez se compléter automatiquement) ; utilisez-le autant que possible car c’est le mécanisme pour lier votre code à votre documentation.
version de la documentation
Avec GitHub, une fois la documentation couplée au code, la revue se fait également dans le même PR. Le bot d’intégration est capable d’identifier jetons intelligents dans tout le code modifié et marque les ajustements déjà effectués (demande de révision à ce moment précis) ou ceux qui n’ont pas été touchés (demande également de révision). Les commentaires individuels ressemblant davantage à des messages de relations publiques, vos réviseurs de relations publiques peuvent approuver chaque section de commentaire une par une, en fonction de leur niveau de confort.
De plus, avec les vérifications automatiques (synchronisation automatique brevetée de Swimm), il est également possible de définir des approbations et des déclencheurs de notification automatiques, ou de les désactiver complètement. Ainsi, votre équipe peut éviter la surcharge de notifications et ajuster la façon dont elle est informée des changements de la manière qui lui convient le mieux.
prends-le d’ici
J’espère que ce regard sur le problème de l’écriture de la documentation vous a touché d’une certaine manière et que les idées ici ont du sens. S’il vous plaît contactez-moi dans les commentaires ci-dessous ou répondez-moi à @AtilaFassina s’il y a quelque chose que vous aimeriez ajouter ou simplement discuter d’une excellente documentation. J’aime une bonne success story !
(vf, il)
