Rédacteur technique

Je commence par utiliser le produit moi-même si c'est possible, parce que cliquer dans quelque chose m'apprend plus en dix minutes que la lecture d'une spec. Je fais une liste de toutes les questions auxquelles je ne peux vraiment pas répondre en utilisant le produit : cas limites, états d'erreur, ce qui se passe si je fais quelque chose dans le mauvais ordre. J'apporte ensuite cette liste à l'ingénieur ou au chef de produit qui l'a construite, plutôt que de lui demander d'expliquer toute la fonctionnalité depuis le début, car une question précise obtient une réponse précise et utile, et respecte son temps. Je lis aussi les tickets existants, les documents de conception ou les fils Slack liés à la fonctionnalité, car une grande partie du raisonnement derrière une décision se trouve là plutôt que dans la spec finale. Une fois que j'ai un modèle fonctionnel de la fonctionnalité, je rédige un plan sommaire et je le partage tôt, avant d'avoir investi du temps dans la rédaction complète, pour que tout malentendu soit détecté quand il coûte encore peu cher à corriger. J'ai fait cela récemment pour un système de permissions avec plusieurs rôles hérités : j'ai construit un petit tableau associant chaque rôle à un niveau d'accès avant d'écrire la moindre phrase du guide, parce que j'avais besoin de comprendre la logique moi-même avant de pouvoir l'expliquer à quelqu'un d'autre.

Je relis par étapes plutôt que d'essayer de tout détecter en une seule passe. La première passe est structurelle : le document répond-il à la question que le lecteur est venu chercher, et l'information est-elle dans l'ordre dont il a besoin, pas nécessairement l'ordre dans lequel on me l'a expliquée. Je vérifie que les titres fonctionnent comme une table des matières autonome, car beaucoup de lecteurs parcourent le document plutôt que de le lire du début à la fin. La deuxième passe porte sur l'exactitude : je suis moi-même chaque instruction, étape par étape, exactement comme elle est écrite, car il est très facile de sauter mentalement une étape quand on sait déjà comment fonctionne le produit. J'ai ainsi repéré des étapes manquantes qui auraient complètement bloqué un lecteur. La troisième passe concerne la langue : couper les mots inutiles, vérifier que la terminologie est cohérente avec notre guide de style et notre glossaire, et m'assurer de ne pas avoir utilisé deux termes différents pour la même chose. J'utilise Vale pour des vérifications automatisées de style et de terminologie avant une relecture humaine, ce qui détecte beaucoup de petites incohérences sans qu'une personne ait à les repérer manuellement. Avant publication, je demande à quelqu'un qui ne connaît pas la fonctionnalité, souvent d'une autre équipe, de suivre le document à froid et de me dire où il a buté.

Je pars de la tâche que le lecteur essaie d'accomplir, pas de tout ce que je sais sur la fonctionnalité. Un développeur qui intègre une API a besoin d'exemples de requêtes et de réponses, de détails d'authentification et de codes d'erreur ; il n'a pas besoin de l'historique expliquant pourquoi l'endpoint a été conçu d'une certaine façon, sauf si cela affecte son utilisation. Un utilisateur final qui lit un article d'aide a besoin d'étapes simples et de captures d'écran, et le détail d'implémentation technique ne ferait que gêner. Quand l'audience n'est pas claire pour moi, je pose la question directement à la personne qui a fait la demande plutôt que de deviner, car écrire pour le mauvais lecteur double l'effort, une fois pour rédiger et une fois pour réécrire. Pour des audiences mixtes, je sépare parfois un document en deux : une section de démarrage rapide pour quelqu'un qui veut avancer immédiatement, et une section de référence en dessous pour quelqu'un qui a besoin du détail complet. Je prête aussi attention à ce que demandent réellement les tickets support et les questions sur les forums communautaires, car cela m'indique où se trouve la vraie confusion plutôt que là où je la suppose. Si personne n'a jamais posé de question sur une section, c'est souvent le signe qu'elle peut être raccourcie.

Le levier le plus important est de faire de la documentation une partie du processus de release plutôt qu'une chose qui arrive après coup. Je pousse pour que la doc soit un élément de la checklist avant qu'une fonctionnalité ne soit livrée, pas une tâche de suivi, car une documentation écrite après le lancement finit systématiquement dépriorisée une fois que l'équipe passe au sujet suivant. Je travaille en Markdown avec notre documentation stockée aux côtés du code dans Git, donc une mise à jour de documentation peut passer par la même pull request que le changement de code, et les relecteurs voient les deux ensemble. Pour les zones qui changent souvent, comme la documentation de référence des API, je génère autant que possible directement à partir de la spec OpenAPI plutôt que d'écrire à la main un contenu qui finira par se désynchroniser. Je fais aussi un audit périodique, en passant en revue les pages les plus consultées chaque trimestre pour vérifier qu'elles correspondent toujours au produit actuel, car même un bon processus laisse parfois passer des choses. Quand je trouve un contenu obsolète pendant une revue de tickets support ou de retours, je le corrige immédiatement plutôt que de le mettre de côté pour plus tard, car une petite correction prend quelques minutes alors qu'un arriéré de documentation périmée prend des jours à rattraper.

Je documentais une fonctionnalité d'export de données où deux ingénieurs m'ont donné des réponses différentes sur ce qui arrivait aux enregistrements supprimés : l'un disait qu'ils étaient exclus automatiquement, l'autre qu'ils étaient inclus sauf filtrage manuel. Plutôt que de choisir une réponse au hasard en espérant qu'elle soit juste, j'ai fait un test rapide moi-même : j'ai créé un enregistrement, je l'ai supprimé, et j'ai lancé l'export pour voir ce qui se passait réellement. Cela a réglé la question factuelle en environ quinze minutes, plus vite que de continuer les allers-retours sur Slack. Il s'est avéré qu'aucun des deux ingénieurs n'avait entièrement raison : les enregistrements supprimés étaient exclus par défaut mais réapparaissaient si un certain filtre était activé, un cas limite que personne n'avait mentionné. J'ai documenté clairement ce comportement précis, y compris le cas limite, et je l'ai signalé à l'équipe comme quelque chose à confirmer comme intentionnel, car il n'était pas évident que cela devait fonctionner ainsi. La leçon que j'en ai tirée, c'est que quand les sources ne sont pas d'accord, tester le produit réel est souvent plus rapide et plus fiable que d'essayer d'arbitrer entre les souvenirs de deux personnes sur la façon dont quelque chose a été construit.

Un ingénieur voulait que la référence API inclue chaque paramètre interne disponible sur un endpoint, y compris plusieurs utilisés pour du débogage interne et non destinés aux développeurs externes. Ma préoccupation était que les inclure générerait des tickets support de développeurs essayant d'utiliser des paramètres qui n'étaient pas réellement pris en charge pour un usage externe, et que cela encombrerait la page pour les paramètres réellement nécessaires. Je n'ai pas simplement dit non : j'ai sorti trois exemples de notre file support où des paramètres similaires, non documentés mais visibles, avaient créé de la confusion dans une autre partie de la documentation, pour rendre l'argument concret plutôt qu'une question d'opinion. J'ai proposé un compromis : garder la référence publique propre, et maintenir une page interne séparée liée depuis notre wiki d'ingénierie pour quiconque dans l'équipe avait besoin de la liste complète des paramètres. L'ingénieur a accepté une fois qu'il a vu le schéma des tickets support, et la page interne s'est aussi révélée utile pour l'onboarding des nouveaux ingénieurs. J'ai constaté que l'opposition passe mieux quand elle s'appuie sur un exemple précis de ce qui a déjà posé problème, plutôt que sur une préférence générale pour la simplicité.

Notre équipe support a signalé qu'une étape de configuration précise, la connexion d'une intégration calendrier tierce, générait un flux constant de tickets, environ quinze par semaine selon leur système d'étiquetage. J'ai lu un échantillon des tickets et remarqué que la documentation existante supposait que le lecteur savait déjà où trouver la clé API de son calendrier, ce qui n'était pas du tout évident pour les utilisateurs moins techniques. J'ai réécrit la section avec un tutoriel guidé par captures d'écran pour les deux fournisseurs de calendrier les plus courants, ajouté une section de dépannage traitant les trois messages d'erreur précis qui revenaient le plus souvent dans les tickets, et remonté le document dans les résultats de recherche du centre d'aide en actualisant le titre pour correspondre à la formulation que les clients utilisaient réellement en cherchant. J'ai demandé au support d'étiqueter séparément les tickets liés à ce parcours pendant les six semaines suivantes pour qu'on puisse mesurer l'impact réel plutôt que de supposer que ça fonctionnait. Les tickets pour ce problème précis sont passés d'environ quinze par semaine à environ quatre, et ceux qui restaient étaient de vrais problèmes différents, pas la confusion que la réécriture visait à résoudre. Relier la correction à un avant-après mesurable est ce qui a rendu l'amélioration démontrable plutôt qu'anecdotique.

Ma rédaction quotidienne se fait surtout en Markdown, que je préfère pour la documentation technique car c'est léger, ça fonctionne bien avec le contrôle de version, et ça évite que la mise en forme ne parasite le contenu. J'ai travaillé avec des configurations docs-as-code où la documentation vit dans Git aux côtés du code du produit, les changements passent par des pull requests, et un générateur de site statique, j'ai utilisé Docusaurus et MkDocs, construit le site publié à partir des fichiers source. Pour des ensembles de documentation plus grands et plus structurés, j'ai utilisé Confluence, qui fonctionne bien pour des bases de connaissances internes mais est moins adapté à une documentation publique versionnée d'après mon expérience. Pour la documentation d'API en particulier, je travaille à partir de spécifications OpenAPI ou Swagger quand c'est possible, car générer le contenu de référence directement depuis la spec le garde exact à mesure que l'API évolue, plutôt que de maintenir à la main un document qui peut se désynchroniser. J'utilise Vale pour du linting automatisé par rapport à notre guide de style, et Snagit pour des captures d'écran annotées quand un tutoriel visuel est plus utile que du texte seul. Je m'adapte rapidement à une nouvelle chaîne d'outils : ce qui compte le plus pour moi n'est pas un outil précis mais la compréhension du flux de travail sous-jacent, contrôle de version, processus de relecture, pipeline de publication, car cette structure se transfère d'un outil à l'autre.

Je commencerais par un guide de démarrage qui amène un développeur de zéro à son premier appel API réussi en le moins d'étapes possible : authentification, une seule requête d'exemple, et la réponse attendue, rien de plus. Les développeurs qui évaluent s'ils vont utiliser une API décident souvent dans les premières minutes selon la rapidité avec laquelle ils font fonctionner quelque chose, donc cette première page pèse lourd. Ensuite, je structurerais la documentation de référence par ressource ou endpoint, avec des sections cohérentes pour chacun : description, paramètres requis, un exemple de requête, un exemple de réponse, et les codes d'erreur courants avec ce qui les provoque. Je garderais le contenu de référence aussi proche que possible d'une génération automatique depuis la spec OpenAPI, pour qu'il ne se désynchronise pas du comportement réel de l'API. En parallèle de la référence, j'ajouterais des guides orientés tâches pour les cas d'usage courants qui combinent plusieurs endpoints, car un développeur construisant une vraie intégration a généralement besoin de savoir comment plusieurs appels fonctionnent ensemble, pas seulement chacun isolément. J'inclurais aussi un changelog et une politique de versionnage claire, car les consommateurs d'API doivent savoir ce qui a changé et si cela va casser leur intégration existante avant de mettre quoi que ce soit à jour.

Dans la mesure du possible, je suis moi-même chaque instruction exactement comme écrite, en utilisant un environnement de test propre plutôt qu'un environnement déjà configuré depuis des tests précédents, car un environnement propre révèle les étapes de configuration manquantes qu'un environnement déjà réglé masque. Pour tout ce qui implique des exemples de code, j'exécute réellement le code plutôt que de faire confiance à son apparence, car une simple faute de frappe dans un exemple peut bloquer un lecteur bien plus longtemps que le temps qu'il m'a fallu pour faire l'erreur. Pour des affirmations techniques plus complexes que je ne peux pas vérifier moi-même, comme des détails d'architecture interne, je demande à l'ingénieur qui l'a construite de relire le paragraphe précis plutôt que le document entier, car une demande de relecture ciblée obtient une vérification plus soignée qu'un 'peux-tu jeter un œil' sur une longue page. Je garde une courte liste de questions ouvertes pendant la rédaction plutôt que de deviner en espérant avoir raison, et je ne publie pas tant qu'elles ne sont pas résolues. Après publication, je considère les tickets support et les retours des lecteurs comme un contrôle continu d'exactitude : si plusieurs personnes butent au même endroit, c'est souvent le signe que les instructions manquaient de clarté ou que quelque chose a changé dans le produit depuis la rédaction du document, pas que les lecteurs se sont trompés.