IA et documentation technique : écrire sans publier d’erreurs

Une IA peut transformer des notes, un diff ou un module en premier brouillon de documentation. Elle ne sait pas automatiquement si une API est stable, si un exemple est exécutable ou si une décision produit a changé. Utilisez-la pour accélérer la structure et la reformulation, puis ancrez chaque affirmation dans une source du projet : code, test, contrat ou documentation officielle.

Ce que vous allez apprendre

Vous allez préparer un périmètre documentaire, demander un brouillon limité, vérifier ses exemples et organiser une revue qui sépare les faits du code des explications pédagogiques. Cette méthode vise une documentation de développeur : README de module, guide d’intégration, référence d’API ou note de migration.

Prérequis

Réunissez le code concerné, ses tests, le contrat d’API éventuel et la documentation existante. Identifiez une personne ou une équipe capable de trancher les règles métier ambiguës. Préparez une commande de test ou un exemple minimal qui peut être exécuté. Évitez de coller des secrets, des journaux de production ou des données personnelles dans le contexte de l’outil.

Étape 1 : choisir la question à documenter

N’essayez pas de « documenter tout le dépôt ». Choisissez une question d’utilisateur : comment installer la bibliothèque, comment appeler un endpoint, quelle erreur attendre ou comment migrer une option. Une question étroite permet de vérifier le brouillon et évite qu’une IA remplisse les blancs avec des conventions générales.

Donnez un plan clair : public visé, résultat attendu, fichiers de référence, langage et informations à ne pas affirmer. Exemple : « Rédige un guide de démarrage pour l’endpoint de création. Utilise le schéma et les tests fournis. N’indique aucun délai, prix ou garantie. Signale les paramètres sans valeur par défaut démontrée. »

Vérification : lisez le plan sans l’outil. Si vous ne pouvez pas relier chaque section à une source, réduisez le périmètre avant de générer le texte.

Étape 2 : demander une structure avant le texte complet

Demandez d’abord les sections, les prérequis et les exemples nécessaires. Une structure utile distingue le démarrage, les paramètres, les retours, les erreurs, les limites et le dépannage. Pour un guide de bibliothèque, ajoutez une section sur la version testée et les dépendances. Pour une API, ajoutez l’authentification, les statuts et les contraintes d’entrée.

Vérification : comparez chaque titre au code et aux tests. Une section qui ne repose que sur une déduction doit être marquée comme question ouverte ou retirée. Ne laissez pas une formulation élégante créer une fonctionnalité inexistante.

Étape 3 : produire des exemples minuscules et exécutables

Un exemple est plus utile lorsqu’il montre une seule idée. Fournissez les imports, les valeurs nécessaires et le résultat attendu. Si l’IA génère du code, demandez-lui d’indiquer quels fichiers ou contrats ont servi de référence. Copilot peut suggérer des commentaires et des explications de code, mais une suggestion dépend du contexte présent et peut ne pas correspondre aux conventions locales.

Exécutez l’exemple dans un environnement isolé ou adaptez un test existant. Si l’exemple ne passe pas, corrigez d’abord la documentation ; ne contournez pas l’échec en retirant le résultat attendu. Une commande qui exige une clé réelle ou un accès à la production n’est pas un bon exemple de démarrage.

Vérification : faites relire l’exemple par une personne qui n’a pas écrit le module, ou suivez-le vous-même dans une session propre. Les étapes implicites apparaissent vite dans cet exercice.

Étape 4 : séparer description, promesse et hypothèse

La documentation doit dire ce que l’outil fait dans un périmètre donné, pas ce qu’il fera toujours. « Cette fonction renvoie une erreur lorsque telle entrée viole le schéma » est vérifiable par un test. « Cette API est fiable et rapide » est une promesse qui exige une mesure, une période et un contexte. Une IA a tendance à lisser ces distinctions si la consigne ne les impose pas.

Ajoutez les limites utiles : version, plateforme, autorisations, comportement des erreurs et ressources externes. Si une donnée est inconnue, dites-le ou renvoyez vers la personne responsable. Une bonne documentation réduit l’incertitude ; elle ne la masque pas.

Étape 5 : organiser la maintenance

Rattachez la documentation au changement qui peut la rendre obsolète. Un test, une issue ou une revue de code peut servir de rappel. Lorsque l’API change, vérifiez les exemples, les captures de sortie et les liens. Une documentation générée une fois puis oubliée devient une source d’incidents plus convaincante qu’un message d’erreur, donc plus dangereuse.

Vérification : lors d’une modification, recherchez le nom du paramètre, la route ou le symbole dans la documentation. Si rien ne relie les deux, notez la mise à jour comme tâche explicite plutôt que de supposer qu’elle arrivera spontanément.

Faire relire le parcours d’un lecteur réel

Une relecture utile ne porte pas seulement sur l’orthographe. Demandez à une personne qui ne connaît pas le module de suivre le guide en partant du dépôt ou de l’environnement indiqué. Observez où elle hésite : dépendance non annoncée, variable d’environnement absente, commande lancée au mauvais dossier ou réponse d’erreur non expliquée. Ces frictions sont des informations de produit. Corrigez le document et, si nécessaire, l’exemple ou le test qui devait rendre l’étape reproductible.

Cette relecture est aussi l’occasion de vérifier la portée du vocabulaire. Une équipe peut employer un même terme pour une route HTTP, un événement et un objet métier. Dans la documentation, donnez un nom précis et un lien vers sa définition plutôt que de compter sur une habitude interne. Le lecteur gagne du temps, et l’IA dispose d’un contexte plus stable lors de la prochaine mise à jour.

Problèmes fréquents et solutions

L’IA invente un paramètre ou une option

Demandez la source exacte de l’affirmation. Si aucun fichier, test ou contrat ne l’établit, retirez-la. N’essayez pas de la rendre vraie dans le code uniquement pour sauver le brouillon.

Les exemples sont trop longs

Scindez-les par objectif. Un lecteur doit pouvoir distinguer l’installation, l’appel minimal et la gestion d’erreur sans modifier dix lignes à la fois.

Le texte réutilise un jargon interne

Ajoutez une définition courte au premier usage et demandez une reformulation pour le niveau du lecteur. Gardez toutefois les noms techniques nécessaires afin qu’il puisse les retrouver dans le projet.

FAQ

Une IA peut-elle produire la référence complète d’une API ?

Elle peut accélérer un brouillon, mais la référence doit être confrontée au contrat, au code et aux tests de la version publiée.

Faut-il donner tout le dépôt à l’outil ?

Non. Le contexte minimal pertinent réduit les erreurs et l’exposition de données inutiles.

Comment vérifier un exemple ?

Exécutez-le dans un environnement contrôlé ou transformez-le en test. Un bloc non exécuté est une hypothèse, pas une preuve.

Peut-on documenter du code ancien sans tests ?

Oui, mais il faut annoncer les incertitudes et créer des observations ou tests ciblés avant de présenter le comportement comme garanti.

Les commentaires générés remplacent-ils un guide ?

Non. Les commentaires expliquent une zone locale ; un guide doit aussi répondre au contexte, aux prérequis et aux limites du lecteur.

Conclusion

L’IA est efficace pour amorcer une documentation technique, à condition que le code, les tests et la revue humaine restent la source d’autorité. Commencez petit, exécutez les exemples et rendez les limites visibles.

Sources et limites

• GitHub Docs — suggestions de code et commentaires
• GitHub Docs — explorer une base de code avec Copilot
• GitHub Docs — écrire des tests avec Copilot

Les fonctionnalités de Copilot et les intégrations varient selon le client et le plan. Cette méthode ne garantit ni l’exactitude d’un brouillon ni la compatibilité d’un exemple avec toutes les versions.