Documentation du code simplifiée —

Tout ce qui entoure la documentation logicielle est difficile, qu’il s’agisse d’allouer du temps pour le faire ou de le tenir à 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 déployés pour créer et maintenir une documentation attrayante dépassent l’investissement en temps et une planification appropriée.

Penny ou Dime

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 lorsqu’ils sont comparés aux fonctionnalités que nous proposons et aux revenus qui en découlent. Ainsi, lorsqu’il s’agit d’écrire et d’éduquer nos pairs sur ces fonctionnalités afin qu’ils deviennent plus capables d’interagir avec leur code, nous remettons souvent en question la valeur de ces minutes par opposition à 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. Revenons au code. Et nous venons de gagner quelques centimes de temps. Avancez un peu; un collègue doit se lancer 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 sous commencent à accumuler des intérêts maintenant. Heureusement, il y a quelques commentaires dans le code. Il est bon de savoir que src signifie en fait sourceet function sort(a, b) prend deux entiers. Mais le raisonnement n’est pas vraiment là, alors continuons à creuser. La demande d’extraction n’a pas de description, git blame n’aide pas parce que qui a écrit le code n’est pas là. Je suppose qu’il est temps de jouer à des trucs de détective et d’ingénieur inverse. Ces centimes sont des centimes maintenant. Décrire a une surcharge cognitive beaucoup plus faible que l’investigation. Ainsi, 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 développeur, pour le meilleur ou pour le pire. Et l’expérience du développeur détermine la quantité de concentration que les développeurs peuvent mettre sur le code qui compte vraiment au lieu de se frayer un chemin à travers les mauvaises herbes.

Brosser les dents

J’espère que nous pouvons tous convenir que se brosser les dents est quelque chose d’important à faire tous les jours. Ce n’est pas le genre d’habitude qu’on peut tout faire le vendredi et compenser les jours sautés. Et dans ce cas, la documentation est un peu similaire. Bien sûr, nous pouvons tout écrire d’ici la fin du trimestre, mais ce sera beaucoup plus difficile et 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 la documentation.

Enlever les obstacles

Malheureusement, la plupart d’entre nous ne parviennent pas à créer l’habitude d’écrire de la documentation, car le flux de travail est souvent plein de frictions. Nous terminons le code, fermons le fichier (ou l’IDE, ou le projet), et sautons sur un éditeur Markdown (ou Jira, ou un Wiki, etc.), et maintenant nous devons trouver le bon endroit pour mettre les connaissances que nous que vous venez de créer, soumettez-le pour révision — 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é, c’est fait. Vous avez ma sympathie.)

Au fur et à mesure que le processus avance, les décisions soulèvent des questions. Et oui, la pratique rend parfait — mais idéalement, nous n’aurions pas besoin de passer autant de temps (et d’énergie !) pour effectuer la diligence raisonnable. Cette friction travaille contre nous dans le maintien de l’habitude, et le temps que nous avons passé à trouver l’endroit où mettre le code a épuisé notre motivation.

Connectez les pièces mobiles

Comme d’habitude, la solution du développeur à un problème de friction est automatisation. Eludez les travaux fastidieux et répétitifs en les rendant dérivés. nager accomplit cela en prenant quelques-unes de ces nombreuses décisions pour vous dans ce qu’ils appellent un « écosystème de documentation » – une dénomination très appropriée.

1. Où mettre la documentation ? Juste là, avec le code.
2. Quand rédiger la documentation ? Au fur et à mesure que vous l’implémentez. Ou lorsque vous ouvrez le PR (au plus tard !).

En résumé, vous écrivez une méthode ; vous expliquez la méthode sur-le-champ. La partie « magique » vient quand, parce qu’ils sont colocalisés, il est possible de documenter directement les paramètres et les variables dans le code au texte dans les docs. De cette façon, lorsque le code change, la documentation est consciente qu’elle est désormais obsolète et peut signaler toute votre équipe à ce sujet.

Toute cette automatisation soignée nécessite une petite configuration et éventuellement quelques modifications de vos interfaces de codage et des processus associés.

Coder dans Docs

Si vous utilisez VS Code ou l’un des IDE de JetBrains, il est possible d’avoir une extension/plugin intégré. Une fois le code écrit, une « vague Swimm » 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 puisque c’est le mécanisme pour lier votre code à votre documentation.

Gestion des versions vers Docs

Avec GitHub, une fois la documentation couplée au code, la révision se fait également dans le même PR. Le bot d’intégration est capable d’identifier Jetons intelligents à travers le code a changé et signale soit les ajustements déjà effectués (invitant à réviser sur-le-champ) soit ceux qui n’ont pas été modifiés (invitant également à réviser). Avec des commentaires individuels qui ressemblent davantage à des invites 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 automatiques et des déclencheurs de notification, ou de les désactiver complètement. Ainsi, votre équipe peut éviter la surcharge de notifications et ajuster la manière dont elle est informée des modifications de la manière qui lui convient le mieux.

Prenez-le d’ici

J’espère que cet aperçu du problème de la rédaction de 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)