Utiliser l'IA pour la documentation logicielle

Un assistant, pas un remplaçant

L’intelligence artificielle¹ n’a pas vocation à remplacer le Rédacteur Technique² mais à l'aider dans certains aspects de son métier et amplifier sa valeur.

Elle automatise les tâches répétitives, centralise les ressources lexicales et facilite la production, pour permettre au Rédacteur Technique de se consacrer à l’essentiel, à sa valeur ajoutée : expliquer clairement des concepts complexes, concevoir une architecture documentaire cohérente et être la voix à la fois des concepteurs et des utilisateurs. Un ensemble de compétences très humaines.

L'ensemble des tâches que l'on peut souhaiter confier à l'IA est évidemment réalisable sans : nous l'avons bien fait jusqu'à présent. En :

• se munissant de dictionnaires, de lexiques, de manuels de styles
• interrogeant différentes personnes ; en cherchant par nous-même (ce qui permet de bien apprendre)
• mobilisant nos nombreuses connaissances
• faisant appel aux acquis de notre expérience

...nous pouvons fort bien rédiger une excellente documentation. Avec une gestion du temps et une répartition des tâches certainement différente, mais le résultat sera là.

C'est d'ailleurs cette capacité à savoir réaliser "sans" qui permet de bien faire "avec" et de garder le contrôle.

L'IA : un soutien indéniable

Il ne s'agit pas de demander à l'IA de faire à notre place, de se substituer à notre rôle voire de prendre notre poste dans l'entreprise. Il s'agit pour le Rédacteur Technique de se faire assister par l'IA pour être plus performant.

L'IA aide à réfléchir, accélère les workflows sans sacrifier la qualité et augmente la qualité sans dénaturer le travail du Rédacteur.

L'IA est d'autant plus utile que le Rédacteur Technique est isolé et/ou travaille en solo. Elle est alors une sorte d'interlocuteur et co-équipier qui accepte de répondre aux questions, veut bien relire dans le détail (et sans remettre aux calendes grecques), fait des remarques pertinentes qu'il complète de suggestions.

L'apport de l'IA

Indéniablement, l'IA est une aide précieuse car elle apporte à la fois :

• Gain de temps sur les tâches de mise en forme, conversions et formatage. Mais l'inspiration créative peut rester de votre côté.

• Cohérence terminologique grâce à l’accès instantané à de nombreux lexiques et guides de style.

• Assistance à la relecture avec détection systématique des incohérences, typos et variations lexicales. Le mot "systématique" est essentiel.

• Production d’exemples et snippets multilangage à partir de spécifications.

Ces apports transforment le temps libéré en valeur ajoutée. Vous sortez la tête de cet ensemble de tâches chronophages et fastidieuses pour prendre de la hauteur et vous adonner au meilleur : la recherche de sens, la conception d’une expérience utilisateur et l'architecture d'une documentation évolutive.

Quand j'ai commencé, j'ai intégré dans ma pratique le "MSTP, Microsoft Manual Of Style For Technical Publications" (2ème édition, sur CD-Rom s'il vous plaît).
Bien qu'imprégnée de ce manuel, je ne peux pas garantir en tant qu'être humain une application stricte et systématique de ses principes. L'IA le peut.

Cas d'usage

La documentation d'API est le 1er cas d'usage pour l'IA au service du Rédacteur Technique (ou du développeur lorsque celui-ci doit faire lui-même la documentation). Plus largement, l'interprétation de code dans le but de le documenter.

Évidemment, il est indispensable d'obtenir l'autorisation avant de coller du code, potentiellement confidentiel, dans un assistant IA. Ou mieux, il convient d'utiliser le même que les développeurs (tels que Cursor, GitHub Copilot ou Claude Code).

Documentation technique

Objet	Usage
Doc d'API	- Génération de pages à partir d’une spécification OpenAPI. - Génération de code snippets exécutables et exemples multilangages. - Préparation de scénarios d’usage.
Compréhension de code	Analyse de modules peu ou mal commentés pour en extraire intentions, paramètres et exemples d’utilisation utilisables en documentation. J'ai déjà du documenter un SDK avec du code pas commenté, c'est "challengeant" 🧠
Diagrammes et schémas	Création de diagrammes (Mermaid par exemple) à partir d’un prompt, d’un texte ou de code pour illustrer flux et architectures.

Travail préparatoire

L'IA pouvant parcourir plus de sites que vous-mêmes en moins de temps, un usage courant est de lui demander de collecter et fournir des informations sur un sujet, avec ou sans liens vers des ressources externes.

Ce qui permet de récupérer des connaissances pour un contexte, soit pour se former soi-même pour une meilleure compréhension du sujet, soit dans l'optique de rédiger un texte.
Lorsqu'un LLM interne existe, il permet de parcourir l'ensemble des ressources de l'entreprise, ce qui peut éviter par exemple de partir à la chasse aux user stories et aux esquisses de documentation made in R&D, de parcourir des repositories, des spécifications et autres documents produits de manière plus ou moins organisée.

Rédaction et optimisation linguistique

La production d'écrit, dans sa langue maternelle ou en anglais, est constitutif de la rédaction technique. Une bonne écriture est une compétence majeure.
On entend par "bonne écriture" : un bon niveau de langue (orthographe, choix du vocabulaire) et une formulation adaptée au lectorat cible.

Le lectorat cible peut être différencié par rôle : utilisateur, professionnel, développeur, etc. mais aussi par pays. Ce qui implique une connaissance des vocabulaires spécifiques, par exemple, ou des usages particuliers.

L'IA est alors comme un filet de sécurité, ayant accès à la plus grande bibliothèque du monde, pour contrôler grammaire, vocabulaire, ponctuation et ton dans vos productions. L'IA est l'assistant idéal pour vérifier, corriger, suggérer et reformuler.

Objet	Usage
Langue	- Reformuler, améliorer/alléger le phrasé, proposer du vocabulaire alternatif, mieux adapté au contexte et/ou au lecteur cible - Corriger la grammaire, le vocabulaire, la typographie en fonction de la langue - Adapter le lexique au contexte ou au canal publication
Contenu	- Suggérer des enrichissements et des développements - Générer, à l'inverse, une synthèse, une description, un résumé - Proposer des (sous-)titres - Fournir des définitions pour certains termes, afin de lever les ambiguïtés et ainsi, éviter les hallucinations (cf. Rédiger pour les LLMs)
Révision	- Contrôler la capitalisation des titres, la ponctuation, les abréviations... - Appliquer un guide de style (IBM's, Microsoft's ou Google’s Style Guide)

Mise en forme et styles

Je pars du principe que le choix du format de publication reste dans les compétences du Rédacteur Technique.
L'IA peut vous se tenir à disposition pour vous préparer une version préliminaire d'un site Web, un document Word ou une page en Markdown, elle est prête à tout sans avoir d'avis.

De même, pour la partie créative de la mise en page, l'impulsion doit venir du Rédacteur Technique. Il/elle se base sur sa pratique, son expérience, la charte graphique en vigueur, les demandes des différents stakeholders, etc. pour proposer un design. L'IA peut après venir en soutien pour la mise en application de tout ou de certains points de ce design.

Différents outils tels Canva Magic Design™ permettent de générer de superbes designs à partir de votre prompt et/ou de vos documents. Mais ils ne sont pas forcément adaptés pour de la documentation technique.

Au Rédacteur Technique donc, la partie créative et la direction via les prompts ; à l'IA bien volontiers la réalisation de tâches chronophages inhérentes à la mise en forme et au design de documents. Telles que :

Objet	Usage
Format	- Formatter du Markdown (ou AsciiDoc ou RestructuredText) - Passer d'un format à un autre - Convertir un document (par exemple, Word → Markdown)
Styles	- Créer une CSS - améliorer une CSS - créer une version pour mobile
Tableaux	- Changer la structure de tableaux (déplacer les en-têtes de colonne vers les lignes par exemple) - changer l'apparence de tableaux et proposer différents styles - générer des tableaux à partir de texte

Des convertisseurs existent déjà depuis plusieurs années pour passer de Word à Markdown et inversement. L'apport de l'IA c'est la centralisation de tous ces outils dans un unique assistant. Ainsi que le suivi d'une tâche à une autre, qui permettent une progression dans le travail.

Révision et contrôle qualité

Comme je le disais plus haut, l'IA peut être un formidable co-équipier : celui qui veut bien relire, et relire attentivement, sans jugement négatif ou subjectivité.
On peut donc confier à l'IA les tâches de révision suivantes :

Objet	Usage
Vérifier	- Contrôler l'application des règles : typographie, titres, terminologie. - Faire une passe sur la cohérence dans la page ou entre plusieurs pages.
Valider	Valider la pertinence utilisateur, en fonction de scénarios et du contexte.
Tester	Tester l’affichage, l'accessibilité et la responsivité du site Web avec des outils IA spécifiques.

Vous pouvez aller plus loin en demandant à l'IA des propositions d’optimisations SEO orientées documentation (par exemple, à insérer dans les en-têtes de page). Ou d'exécuter des règles de vérification automatisées (linting docs, tests d'exécution des snippets).

Limites

L'IA est un assistant, pas un décisionnaire.
Le Rédacteur Technique doit rester à l'initiative, via les prompts ; aux commandes via des affinages manuels ou par de nouveaux prompts ; et enfin au contrôle final via une post-édition obligatoire afin d’éviter hallucinations et écarts de ton.

On évitera donc de confier à l'IA :

• la rédaction complète de la documentation utilisateur sans contexte produit, scénarios et retours réels.

• la production d’exemples techniques non vérifiés : tout snippet généré doit être exécuté ou revu.

• les contenus réglementaires, liés à la sécurité critique ou présentant une forte responsabilité juridiqu sans revue experte. Sans perdre de vue que la documentation est un produit contractuel.

Cas de la documentation utilisateur

Plus elle est fonctionnelle et moins elle peut être confiée à l'IA.
Une documentation utilisateur est fortement liée à un contexte et requiert une utilisation réelle du produit par le Rédacteur Technique (je dis souvent que nous sommes des beta testeurs) afin d'en retirer une connaissance approfondie qui sera retranscrite dans un scénario d'utilisation adapté à l'utilisateur final.

En l'absence de :

• contexte (métier, rôle, cas d'usage...)
• données crédibles (celles qu'il faut saisir dans l'application pour obtenir un vrai résultat)
• empathie pour l'utilisateur final (le Rédacteur Technique ne doit-il pas "se mettre à la place de l'utilisateur final" ?)
• retour d'expérience utilisateur (issus du support par exemple mais pas uniquement)
• règles d'écriture, si possible proche des vôtres

Alors la documentation risque d'être un corpus inutilisable, contenant de vieux/mauvais tics de langages, et des propos inintéressants passant à côté du vrai objectif d'une documentation : vous guider pour que vous tiriez le meilleur parti de votre application.
Vous me direz, certains humains aussi peuvent produire des documentations inutilisables...

Cas des hallucinations

Vous pouvez contribuer à éviter autant que possible les hallucinations ressorties par l'IA.

• Pour les exemples de code, il est préférable de continuer à demander à un développeur. Et de lui faire valider les variantes de cet exemple dans d'autres langages le cas échéant.

• Alimentez l'IA avec vos questions par petits morceaux, étapes par étapes, et soyez vigilants à chaque moment du processus. Ne prenez rien pour argent comptant, et astreignez-vous chaque fois que nécessaire à une contre expertise en dehors de l'IA.

Bref, vérifiez, contrôlez, maîtrisez. Vous avez gagné du temps sur les tâches à moindre valeur ajoutée, réinvestissez-le dans plus de contrôle qualité.

Question de limites

Les limites doivent être poser par le Rédacteur Technique, qui doit garder la maîtrise de son workflow du début jusqu'à la fin.

Il doit être capable a posteriori de :

• relire ses prompts et expliquer ses choix ;
• de pointer les hallucinations et les corriger ;
• lire le code produit par l'IA et de comprendre ce qui a été produit ;
• refaire dans un cas similaire mais non identique (ce qui indique qu'il a appris quelque-chose de l'IA) ;
• maintenir la documentation (a fortiori si c'est un site Web) à tous les niveaux, même pour les parties où l'IA est intervenue.

Le Rédacteur Technique est l'auteur de sa documentation, il en a donc la propriété intellectuelle mais aussi la responsabilité.

Conclusion

En résumé, l’IA ne remplace pas, elle amplifie.

L’IA multiplie les capacités opérationnelles d’une équipe de documentation, tout en renforçant le rôle stratégique du Rédacteur Technique.

Des services techniques optimisés par l'IA bientôt disponibles

---

Notes

¹ IA ou les IAs (générative, conversationnelle) selon que l'on veuille être générique ou précis.
² Rédacteur ou Rédactrice Technique bien sûr.

---

©Author: Florence Venisse, STW – Version initiale du 26/092025.