Read the fucking manual — Ah, la documentation technique. Bien souvent négligée, parfois farouchement défendue… Ce qui est sûr, c’est qu’elle ne laisse aucun développeur de marbre.
Je ne vais pas vous le cacher, ça fait longtemps que je souhaite traiter ici ce sujet (et qui sait, peut-être d’autres), même si celui-ci s’avère un peu plus sérieux que mes contenus habituels.
Alors on en rigole, c’est sûr... Mais dans le fond, la documentation — et je parle notamment de la documentation technique — c’est quand même quelque chose qui nous concerne de manière très concrète et qui joue un rôle crucial dans les projets de développement.
D’ailleurs, si on y réfléchit bien, celle-ci (ou ne serait-ce que son existence) peut carrément avoir un impact sur notre organisation, notre productivité, et même notre bien-être (si, si) !
# En partenariat avec JetBrains
Je t’aime, moi non plus
Ce n’est pas une grande nouveauté : les développeurs sont très souvent réticents à l’idée de rédiger de la documentation technique. Mais paradoxalement, ce sont aussi les premiers à se plaindre lorsque celle-ci est inexistante ou de mauvaise qualité.
Pourtant, une documentation bien écrite est une véritable bouffée d'air frais pour tout dev dans la tourmente, toi-même tu sais.
La doc, un mal pour un bien ? Ça ne fait aucun doute mes p’tits potes !
Rédigez-vous de la doc technique pour vos projets ?
— Les Joies du Code (@lesjoiesducode) August 2, 2024
Le principal défi pour les développeurs lorsqu'il s'agit de rédiger une documentation technique de qualité est souvent le manque de temps.
Reléguée au second plan au fil des urgences et des nouvelles choses à coder, la documentation finit ainsi dans 95 % des cas par sombrer dans l’oubli, tout comme les connaissances complètes qui l’entouraient pourtant à l’instant T.
Découvrez Grazie, l'assistant d'écriture par IA pour les professionnels de la tech
De plus, il faut admettre qu’une grande partie des développeurs, perçus comme "taiseux", n'ont pas forcément d'appétence pour ce genre de tâche.
Il est parfois nécessaire de définir un rédacteur attribué dans une équipe (sur certains gros projets, ce genre de profil peut même être dédié à 100% à cette tâche).
L’importance de la doc technique
Avant de commencer à vous énerver sur sa rédaction, il est important de comprendre pourquoi une bonne documentation technique est essentielle.
Premièrement, son utilité première selon moi : la maintenance.
Derrière ce terme des enfers, j’englobe toute forme de prise en charge du projet concerné : la correction de bugs, le développement d’évolutions, mais aussi la compréhension de sa structure, ses concepts et spécificités.
Une documentation bien rédigée, c’est l’assurance de pouvoir trouver rapidement et efficacement des réponses, et donc de gagner du temps tout en préservant son énergie.
Vient ensuite le sujet non négligeable de la transmission des connaissances.
Une documentation claire et détaillée facilite énormément l'intégration de nouveaux développeurs, qu’ils soient nouveaux au sein de la structure ou par exemple mainteneurs en urgence sur le projet pour contrecarrer des absences.
Là encore, dix points pour Gryffondor.
Disposer d’une documentation technique aide également à maintenir une compréhension partagée du projet au sein des équipes, et peut encore vous faire gagner du temps en évitant el famoso point "partage de connaissances" dans votre agenda. On adore.
Enfin, pour celles et ceux parmi vous qui disposent de repos exposés sur GitHub et cherchent à côtoyer les étoiles (vous l’avez ?), sachez qu’une doc sur vos projets, même minimaliste, vous aidera à être mieux référencé sur la plateforme (eh ouais).
Le fichier README.md est souvent le premier point d’entrée pour les utilisateurs et les moteurs de recherche de GitHub. Des README bien structurés, incluant des mots-clés pertinents, des instructions claires, des exemples de code, et des liens vers d'autres sections de la documentation peuvent ainsi grandement améliorer la visibilité de vos projets.
Vous n’écrivez pas (que) pour vous
L’un des éléments principaux à garder en tête lorsqu’on s’attelle à la rédaction d’une documentation, c’est de la rendre claire et accessible au plus grand nombre.
Pour cela, il est crucial de limiter au maximum l’usage de jargon, d’acronymes, et d’enchaînements d’initiales, qui tendent à ajouter une couche de complexité plutôt qu’à faciliter la compréhension d’un sujet.
C’est sûr, ce projet, vous l’avez poncé pendant des mois, voire des années.
Et comme beaucoup, vous avez inévitablement pris l’habitude d’utiliser un max d’abréviations et de raccourcis à l’écrit ou à l’oral pour évoquer telle fonctionnalité, tel module, tel outil, telle donnée ou que sais-je wesh.
Toutes ces abréviations et initiales ultra techniques, quand on est dans le feu de l’action, c’est pratique, rapide, efficace (quelqu’un a dit agile ?! 🤬).
Mais pour un œil extérieur, complètement vierge de toute information, c’est juste la panique totale. Vraiment.
Et je ne vous parle même pas du syndrome de l’imposteur que ce genre d’informations en vrac peut nourrir chez ceux qui vous liront.
Attention : il n’est pas question de bannir complètement ces acronymes, certains sont parfaitement justifiés. Mais il est essentiel de les expliciter clairement, et pourquoi pas plusieurs fois si nécessaire.
Les clés d’une documentation technique réussie
Pour qu'une documentation technique soit efficace, il est recommandé de respecter 3 principes fondamentaux, les 3C (qui ne sont probablement pas ceux auxquels vous pensez 🙄) : clarté, concision, cohérence.
Clarté
On utilise un langage simple et sans fioritures, on définit clairement les nouveaux termes, et on évite absolument toute ambiguïté. Les informations complexes doivent être le plus accessible et compréhensible possible.
Se mettre à la place du lecteur et se demander ce qui permettrait de mieux comprendre le sujet constitue également une bonne approche pour la rédaction.
Pour ce faire, il ne faut pas hésiter à inclure, dès que cela fait sens, des schémas, des exemples concrets voire des extraits de code (sans toutefois aller jusqu’à lâcher un copier/coller d’une centaine de lignes).
Travaillez plus rapidement sur vos docs techniques avec Grazie de JetBrains (gratuit)
Concision
Il faut garder les phrases courtes. Se concentrer sur une seule idée par phrase pour améliorer la lisibilité. Comme dans ce paragraphe.
Plus sérieusement, organiser son contenu en morceaux digestes facilite la navigation d’une documentation. Une bonne structure avec des chapitres et des sous-chapitres bien découpés permet par ailleurs d’accéder plus vite aux infos directement depuis le sommaire.
Cohérence
On utilise la même terminologie et le même style tout au long de la documentation pour éviter toute confusion.
La progression logique du document doit guider les lecteurs des concepts de base aux plus avancés. Inclure des liens hypertextes lorsque des concepts sont rappelés peut grandement maximiser l’efficacité de la documentation.
Enfin, il n’est pas toujours nécessaire de sortir l’artillerie lourde pour mettre au point sa doc technique. Le diable est dans les détails : parfois, un simple fichier README bien construit peut parfaitement faire l’affaire. 👌
Une bonne doc est une doc à jour
Ce serait formidable si les docs restaient d’actualité pour toujours. Mais après tout, le passé finit toujours par nous rattraper, n’est-ce pas ?
Au fil des différentes évolutions de votre produit (la méthode à Gilles représente), les descriptions, les étapes, les éventuelles captures d’écran dans votre documentation sont susceptibles de devenir inexactes, voire obsolètes. Comme les devs avec l’IA, mais c’est pas le sujet.
Une bonne documentation est donc une documentation à jour.
Il est recommandé de passer régulièrement en revue ses docs et de traiter leurs mises à jour comme des tâches parallèles au développement.
Inclure la mise à jour de la documentation dans les sprints peut être une bonne habitude, ou au moins lors du déploiement de chaque nouvelle release.
De plus, la relecture et l'optimisation régulières de la documentation sont importantes pour éliminer les redondances, assurer la clarté et maintenir un ton et un style cohérents.
Dans la majeure partie des cas, la documentation ne doit pas être une tâche solitaire : il s’agit d’une responsabilité collective.
Les relectures aident à s’assurer que tout le monde est sur la même longueur d’onde et en accord avec les concepts et points traités.
Pour finir, la standardisation des processus est également essentielle. Avoir le même fonctionnement pour tous les projets, par exemple en utilisant le même template pour toutes les docs, permet de maintenir une cohérence et une uniformité dans les pratiques documentaires.
Concentrez-vous sur le code, Grazie s’occupe du texte
Plutôt que de terminer cet article en vous laissant avec une crise existentielle face à toutes ces docs que vous n’avez jamais écrites, je me suis dit que j’allais vous proposer une solution.
Ou tout du moins une amorce de solution.
JetBrains vient de lancer Grazie, un assistant d’écriture par IA pour les développeurs, qui peut de toute évidence être employé pour procéder à de la rédaction de documentation technique.
Cet assistant propose d’améliorer vos textes en corrigeant la grammaire, l’orthographe, en reformulant, et même en touchant à des détails comme la ponctuation et le ton employé.
Vous avez par exemple la possibilité de demander à l’outil d’adopter un ton professionnel ou plus décontracté selon l’audience concernée par votre texte (que ce soit pour vos bros de pair programming ou votre N+1 et autres N++).
Grazie effectue une relecture instantanée de votre texte et permet une saisie automatique assistée, semblable à ce que vous connaissez avec le code, mais cette fois-ci pour du texte.
L’IA derrière la solution a été entraînée sur des jeux de données liés au monde de la tech, rendant ses suggestions particulièrement pertinentes.
Pour éviter de perdre trop de temps à déchiffrer les specs pompeuses du commercial, qui aime ajouter des fioritures pour donner l’impression qu’il a travaillé fort, l’assistant vous permet également de résumer un texte en en retenant les points principaux.
Grazie est disponible dans tous les bons IDE de JetBrains (à savoir tous les IDE de JetBrains), mais aussi (et ça c’est une dinguerie) dans les navigateurs Chrome, Safari et Edge sous forme d’extension gratuite !
Cela permet de travailler avec ce nouvel assistant sur des plateformes et services en ligne comme GitHub, Google Docs, Slack, Jira, Bitbucket ou Zendesk (je vous ai vu sourire).
Vous travaillez avec des équipes ou des clients à l’international ? L’assistant Grazie de JetBrains peut là aussi "prendre le lead", comme aime si bien le dire Tristan, le nouveau consultant junior expert en consulting fraîchement sorti d’école. L’assistant permet en effet de traduire de manière très efficace un contenu que vous consultez.
La version gratuite de Grazie est soumise à une limitation sur le volume de base des fonctionnalités de l’IA de JetBrains. Il est important de noter que ce volume, renouvelé chaque semaine, est suffisant selon JetBrains pour répondre aux besoins en écriture de la plupart des professionnels de la tech.
L’abonnement à JetBrains AI Pro permet de profiter de Grazie sans cette limitation, tout en donnant accès à plusieurs fonctionnalités supplémentaires (je vous en ai déjà parlé ici).
Et qui sait, avec Grazie, vous pourriez-même enchaîner avec la doc utilisateur, plutôt chanmé avouez.
Allez, j’vous laisse, faut que j’me génère une petite doc pour ma dernière regex de l’espace. 🫡
