Numérique · Bases et gestion des connaissances
Documentation technique
La documentation technique rassemble les documents qui permettent de concevoir, installer, utiliser, maintenir ou intégrer un produit : manuels, guides, références d’API.
Mis à jour le 4 min de lecture
La documentation technique transforme le savoir des concepteurs en informations utilisables par d’autres : utilisateurs, techniciens, développeurs, auditeurs. Elle concerne aussi bien un logiciel qu’une machine industrielle ou un appareil électroménager. Le métier qui la produit est celui de rédacteur technique (technical writer).
Les grands types de documentation technique
| Type | Public | Exemples |
|---|---|---|
| Documentation utilisateur | Utilisateurs finaux | Manuel, guide de démarrage, aide en ligne, notice |
| Documentation d’installation et d’exploitation | Administrateurs, techniciens | Guide d’installation, procédures d’exploitation (runbooks), plans de reprise |
| Documentation de maintenance | Techniciens de maintenance | Gammes de maintenance, nomenclatures, schémas |
| Documentation développeur | Développeurs | Référence d’API, SDK, exemples de code, guide de contribution |
| Documentation de conception | Équipe projet | Spécifications, architecture, décisions techniques (ADR) |
| Documentation réglementaire | Autorités, auditeurs | Dossier technique de marquage CE, déclarations de conformité |
Dans l’Union européenne, plusieurs textes (directive Machines, règlement sur les dispositifs médicaux, etc.) imposent une notice d’instructions dans la langue de l’utilisateur et un dossier technique tenu à disposition des autorités.
Le cadre Diátaxis : quatre besoins, quatre formes
Très utilisé pour la documentation logicielle, le cadre Diátaxis (formalisé par Daniele Procida) distingue quatre types de contenus qu’il ne faut pas mélanger :
| Type | Orientation | Question du lecteur | Forme |
|---|---|---|---|
| Tutoriel | Apprentissage | « Je débute, guide-moi » | Parcours pas à pas avec résultat garanti |
| Guide pratique (how-to) | Tâche | « Comment faire X ? » | Étapes précises, sans théorie |
| Référence | Information | « Quelle est la valeur, l’option, la syntaxe ? » | Descriptions exhaustives, tableaux |
| Explication | Compréhension | « Pourquoi ça fonctionne ainsi ? » | Texte argumenté, contexte, choix de conception |
Une page qui mélange tutoriel, référence et explication ne sert bien aucun lecteur. Cette distinction s’applique aussi à une base de connaissance.
Règles de rédaction
Structure
- Un objectif par page, annoncé dans le titre (« Configurer l’authentification à deux facteurs »).
- Prérequis indiqués avant les étapes (droits, versions, matériel).
- Étapes numérotées, une action par étape, résultat attendu indiqué.
- Avertissements placés avant l’action dangereuse, pas après.
Style
- Phrases courtes, voix active, impératif pour les instructions (« Cliquez sur Enregistrer »).
- Terminologie constante : un même objet porte toujours le même nom. Un glossaire aide.
- Exemples concrets et, pour le code, exemples complets et testés.
- Pas d’ambiguïté sur les unités, les versions, les valeurs par défaut.
Pour les produits industriels et aéronautiques, des langues contrôlées comme le Simplified Technical English (norme ASD-STE100) limitent vocabulaire et tournures pour éviter les erreurs d’interprétation.
Visuels
Schémas, captures annotées et tableaux remplacent avantageusement de longues descriptions, à condition d’être tenus à jour avec l’interface.
La documentation comme du code
Dans le logiciel, une pratique répandue consiste à traiter la documentation comme du code (docs as code) :
- rédaction en texte léger (Markdown, reStructuredText, AsciiDoc) ;
- stockage dans le même dépôt Git que le code, avec relecture par demande de fusion ;
- génération automatique d’un site par un outil comme Sphinx, MkDocs, Docusaurus ou Antora ;
- vérifications automatiques (liens morts, orthographe, exemples exécutés).
Les références d’API peuvent être générées depuis le code ou depuis une description normalisée (spécification OpenAPI pour les API web).
Les outils
| Besoin | Outils courants |
|---|---|
| Docs as code | Markdown + Git + MkDocs, Sphinx, Docusaurus, Antora |
| Documentation structurée (industrie) | DITA XML, S1000D (aéronautique et défense), outils de rédaction structurée |
| Wiki technique | Confluence, Wiki.js, BookStack, MediaWiki |
| Centre d’aide produit | Document360, Zendesk Guide, outils de portails développeurs |
| API | OpenAPI avec Swagger UI ou Redoc |
Maintenir la documentation
Une documentation technique vieillit à chaque version du produit. Les bonnes pratiques :
- intégrer la mise à jour de la documentation à la définition de « terminé » d’une évolution ;
- versionner la documentation comme le produit (une version de doc par version majeure) ;
- indiquer clairement les fonctionnalités obsolètes ;
- recueillir les retours des lecteurs (« Cette page vous a-t-elle aidé ? ») et des équipes support ;
- conserver l’historique des décisions de conception, utile des années plus tard.
Une documentation complète et à jour est aussi ce qui permet aux assistants d’IA internes de répondre juste (voir RAG), et c’est l’un des principaux moyens de rendre explicite le savoir tacite des ingénieurs (voir connaissances tacites et explicites).
Questions fréquentes
Quelle différence entre documentation technique et documentation utilisateur ?
La documentation utilisateur est une partie de la documentation technique, destinée aux personnes qui utilisent le produit. La documentation technique au sens large comprend aussi la conception, l’installation, la maintenance et la documentation pour développeurs.
Qui rédige la documentation technique ?
Des rédacteurs techniques dans les organisations qui en ont, sinon les ingénieurs et développeurs eux-mêmes. Dans tous les cas, les experts du produit relisent pour l’exactitude.
Quel format choisir : PDF, wiki ou site ?
Un site web consultable et recherché convient à la plupart des usages et se met à jour facilement. Le PDF reste utile pour une notice livrée avec un produit ou un dossier réglementaire figé.
Combien de temps consacrer à la documentation ?
Il n’existe pas de ratio universel. Le bon indicateur est l’usage : si le support reçoit des questions dont la réponse devrait figurer dans la documentation, elle est insuffisante.