IA et documentation technique : les cas d'usage qui marchent vraiment

J'accompagnais une équipe de 12 développeurs chez un client dans l'édition logicielle. Leur base de code avait 23 services. Zéro documentation. Les nouvelles recrues passaient 3 semaines à poser des questions aux développeurs seniors, qui, eux, perdaient 30 à 45 minutes par jour à répondre. Un coût invisible mais massif, mesuré quand j'ai fait le calcul avec le CTO.

Nous avons organisé un sprint de documentation de 2 jours avec assistance Claude. Résultat : 18 services avaient des READMEs et des docs d'API générés. Temps de révision humaine : 30 à 45 minutes par service. Le lead time d'onboarding est passé de 3 semaines à 10 jours. 18 services documentés en 2 jours, contre 18 semaines si fait manuellement.

L'IA peut automatiser 60% de la documentation technique. Mais pas les 60% auxquels on pense en premier. Les équipes qui espèrent que l'IA va écrire leurs ADR et leur documentation d'architecture sont déçues. Celles qui l'utilisent pour les bons cas d'usage gagnent des heures par semaine.

Ce que l'IA documente bien, et ce qu'elle documente mal

J'ai testé et observé suffisamment de déploiements pour établir une règle simple :

L'IA documente bien le "quoi" : ce que le code fait, comment appeler une API, quels paramètres une fonction accepte, quelle est la structure d'un objet. Ces informations sont dans le code, l'IA les extrait et les formate.

L'IA documente mal le "pourquoi" : pourquoi ce choix d'architecture, pourquoi cette contrainte de performance, pourquoi cette API a été dépréciée. Ces informations ne sont pas dans le code, elles sont dans les cerveaux des développeurs qui ont pris ces décisions.

La règle d'usage : utilisez l'IA pour documenter le "quoi" ; investissez le temps humain sur le "pourquoi".

Cas d'usage 1 : Génération de documentation d'API (ROI élevé)

Le problème : les APIs internes ne sont souvent pas documentées. Chaque développeur qui intègre un nouveau service perd 2 à 4 heures à comprendre les endpoints, les paramètres, et les formats de réponse en lisant le code.

Ce que l'IA fait : à partir du code d'un controller, d'un router Express, ou d'un fichier de routes FastAPI, l'IA génère une documentation structurée (format OpenAPI/Swagger ou Markdown) avec les endpoints, les paramètres, les types, et des exemples.

# Prompt pour Claude/GPT-4
"""
Voici le code d'un router FastAPI. Génère une documentation OpenAPI complète
avec description de chaque endpoint, paramètres, types, et exemples de requête/réponse.

[coller le code du router]
"""

Résultat typique : une documentation OpenAPI utilisable en 5 minutes de génération + 15 minutes de révision humaine pour vérifier l'exactitude et ajouter les informations contextuelles (qui appelle cette API, dans quel flux business, quelles sont les contraintes de rate limiting).

Gain : 3 à 4 heures de documentation manuelle → 20 minutes.

Cas d'usage 2 : Commentaires et docstrings dans le code (ROI moyen)

Le problème : le code existant n'a pas de commentaires. Les fonctions complexes sont difficiles à comprendre sans connaître le contexte de leur création.

Ce que l'IA fait : elle génère des docstrings JSDoc, Python Docstrings, ou JavaDoc pour les fonctions et classes existantes.

// Avant
function calculateEligibility(user, subscription, promoCode) {
    if (!user.verified) return { eligible: false, reason: 'NOT_VERIFIED' };
    if (subscription.status !== 'active') return { eligible: false, reason: 'INACTIVE_SUB' };
    if (promoCode && promoCode.usageCount >= promoCode.maxUsage) {
        return { eligible: false, reason: 'PROMO_EXHAUSTED' };
    }
    return { eligible: true };
}

// Après génération IA
/**
 * Détermine l'éligibilité d'un utilisateur à appliquer un code promo.
 *
 * @param {User} user - L'utilisateur demandant l'application du promo
 * @param {Subscription} subscription - L'abonnement actif de l'utilisateur
 * @param {PromoCode|null} promoCode - Le code promo à valider (peut être null)
 * @returns {{ eligible: boolean, reason?: string }} Résultat de l'éligibilité
 */

Limite importante : l'IA génère des docstrings corrects sur la forme, mais peut se tromper sur la sémantique métier. Toujours réviser pour vérifier que la description correspond au comportement réel. la génération IA réduit le temps d'écriture de 80%, elle ne remplace pas la révision humaine. Voir comment intégrer l'IA dans la code review pour un workflow cohérent.

Cas d'usage 3 : README de service et onboarding (ROI élevé)

Le problème : chaque service d'un système distribué devrait avoir un README qui explique son rôle, comment le démarrer en local, comment le tester, et les variables d'environnement requises. En pratique, ces READMEs sont absents ou obsolètes.

Ce que l'IA fait : à partir du code source (package.json, Dockerfile, docker-compose.yml, code principal), l'IA génère un README structuré.

Prompt type :

Voici le package.json, le Dockerfile, et le fichier main.ts d'un service Node.js.
Génère un README.md complet incluant :
- Description du service et son rôle dans l'architecture
- Prérequis
- Installation et démarrage en local
- Variables d'environnement (liste depuis le code)
- Endpoints principaux
- Comment lancer les tests

Ce que l'humain ajoute : le contexte business (quel problème ce service résout), les dépendances avec les autres services, les décisions d'architecture importantes.

Gain pour l'onboarding : un nouveau développeur avec des READMEs à jour démarre en autonomie 3 à 5 jours plus tôt qu'avec des READMEs absents. Sur une équipe qui recrute 4 personnes par an, c'est 12 à 20 jours de productivité récupérés chaque année.

Cas d'usage 4 : Résumés de PR et commit messages (ROI élevé)

Le problème : les commit messages et descriptions de PR sont soit vides ("fix bug", "update code"), soit trop détaillés pour être lus. L'historique git devient inutilisable.

Ce que l'IA fait : à partir du diff d'une PR, l'IA génère un résumé structuré (ce qui a changé, pourquoi, les impacts potentiels, le plan de test).

GitHub Copilot peut générer des descriptions de PR automatiquement. Alternativement, un script pre-commit qui appelle l'API Claude avec le diff :

# Script pre-commit simplifié
git diff --cached | claude -p "Génère un commit message conventionnel en anglais
pour ce diff. Format: type(scope): description. Types: feat/fix/refactor/test/docs"

Bénéfice secondaire : des descriptions de PR de qualité améliorent le processus de code review, le reviewer comprend rapidement l'intention du changement avant de lire le code. Une étude de l'équipe DevEx de Google (2023) sur la qualité des PRs indique que des descriptions claires réduisent le temps de review de 15 à 25%.

Cas d'usage 5 : Mise à jour de documentation existante (ROI moyen)

Le problème : la documentation existante se désynchronise du code. Une API change, la documentation ne change pas. Un développeur suit la doc et se retrouve avec des erreurs incompréhensibles.

Ce que l'IA fait : comparer la documentation existante avec le code actuel et identifier les divergences.

Prompt type :

Voici la documentation actuelle de l'API /users/{id}/subscriptions :
[documentation]

Voici le code actuel de cet endpoint :
[code]

Identifie les divergences entre la documentation et le code, et propose
une documentation mise à jour.

Limite : l'IA identifie les divergences techniques (paramètres manquants, types incorrects) mais pas les divergences de logique métier. La révision humaine reste nécessaire.

Ce que l'IA ne peut pas documenter

Décisions d'architecture : pourquoi Event Sourcing plutôt que CRUD, pourquoi PostgreSQL plutôt que MongoDB, pourquoi ce découpage en microservices. Ces décisions ont un contexte (contraintes techniques, état de l'équipe, urgence du moment) que l'IA ne peut pas reconstruire. Les ADR (Architecture Decision Records) restent un exercice humain.

Contraintes non-exprimées dans le code : un timeout à 3 secondes dans une config qui existe parce qu'un service tiers SLA garantit 99% de réponses en moins de 2,5 secondes. Sans commentaire humain, l'IA ne peut pas savoir que cette valeur ne doit pas changer.

Le "pourquoi ça ne marche pas" : les runbooks de debugging, les solutions aux problèmes connus, les workarounds pour les bugs connus des dépendances. Ces informations viennent de l'expérience terrain, pas du code.

Comment intégrer l'IA dans le workflow de documentation

Option A : Documentation as part of PR : ajouter à la Definition of Done que toute nouvelle API ou service doit avoir sa documentation générée par IA et révisée par l'auteur. Le reviewer vérifie la documentation comme il vérifie le code.

Option B : Sprint de documentation : une fois par trimestre, un sprint de 2 jours dédié à la mise à jour de la documentation avec assistance IA. Chaque développeur génère la doc de ses services et la révise.

Option C : Automatisation continue : un pipeline CI qui génère automatiquement la documentation OpenAPI à partir des annotations de code et la déploie dans un portail de documentation (Stoplight, Backstage). La doc est toujours à jour avec le code.

La séquence que je recommande : commencer par les READMEs des services critiques (impact onboarding immédiat), puis la documentation des APIs internes (impact developer experience), puis les résumés de PR (impact code review quality).

FAQ sur l'IA et la documentation technique