Une documentation d’application utile est celle qui répond, au bon moment, à la question précise d’un lecteur précis. Elle s’adresse à trois publics qui n’ont pas les mêmes besoins : les utilisateurs (comment faire telle tâche ?), les personnes qui exploitent l’application (que faire quand elle tombe, comment la restaurer ?) et les développeurs (comment est-elle construite, et pourquoi ?). Une bonne documentation est courte, organisée par usage, versionnée avec le code et livrée contractuellement à chaque version.
Pour une PME ou une ETI, l’enjeu dépasse le confort : c’est la documentation qui rend l’application transmissible à une nouvelle recrue, à une nouvelle équipe ou à un nouveau prestataire.
Pourquoi la plupart des documentations ne servent à rien ?
Le scénario est classique. À la fin du projet, l’équipe produit un document volumineux, exhaustif, rédigé en quelques jours. Six mois plus tard, il est obsolète ; un an plus tard, personne ne sait où il se trouve. Michael Nygard le résumait dès 2011 dans son article fondateur sur les décisions d’architecture : les gros documents ne sont jamais tenus à jour.
Trois erreurs expliquent ce gâchis :
- Écrire pour tout le monde à la fois. Un même document mélange captures d’écran pour les utilisateurs, commandes serveur pour l’exploitation et schémas pour les développeurs. Chacun y cherche ses trois pages et abandonne.
- Écrire à la fin. La documentation rédigée après coup reconstitue des choix dont on a oublié les raisons.
- Séparer la documentation du produit. Stockée ailleurs que le code, modifiée par d’autres personnes, elle diverge dès la première évolution.
Les quatre formes de documentation selon Diátaxis
Le cadre Diátaxis, conçu par Daniele Procida, part d’un constat simple : il existe quatre besoins distincts, donc quatre formes de documentation, à ne pas mélanger. Il les répartit selon deux axes : agir ou comprendre, apprendre ou travailler.
| Forme | Le lecteur veut… | Exemple pour une application métier |
|---|---|---|
| Tutoriel | Apprendre en faisant | « Votre première commande fournisseur, pas à pas » pour un nouvel acheteur |
| Guide pratique | Accomplir une tâche précise | « Annuler une facture déjà transmise » ; « Restaurer la base de la veille » |
| Référence | Trouver une information exacte | Liste des statuts d’une commande ; description des champs d’une API |
| Explication | Comprendre le pourquoi | Pourquoi les stocks sont recalculés la nuit ; pourquoi deux bases distinctes |
Appliquer cette distinction change immédiatement la lisibilité. Un guide pratique ne s’encombre pas d’explications ; une page de référence ne raconte pas d’histoire ; un tutoriel ne liste pas toutes les options.
La documentation pour les utilisateurs
Les utilisateurs d’une application métier ne lisent pas de manuel. Ils cherchent une réponse au moment où ils bloquent. La documentation utile pour eux tient en quelques principes.
Organiser par tâche, pas par écran. « Traiter un retour client » est une tâche qui traverse plusieurs écrans ; c’est ainsi que l’utilisateur pense.
Intégrer l’aide dans l’application. Une bulle d’explication sur un champ ambigu, un lien « comment ça marche ? » sur un écran complexe, une page d’aide accessible depuis chaque module : l’aide contextuelle est consultée bien plus que n’importe quel PDF.
Distinguer les profils. Le guide d’un commercial n’est pas celui d’un comptable. Une fiche d’une page par profil et par tâche fréquente vaut mieux qu’un document unique.
Prévoir le parcours d’arrivée. Pour un nouvel utilisateur, un tutoriel de prise en main de trente minutes, éventuellement en vidéo, réduit fortement les demandes au support. C’est un pilier de la conduite du changement.
Une bonne interface réduit d’ailleurs le besoin de documentation : si un écran exige trois paragraphes d’explication, c’est peut-être l’écran qu’il faut revoir, comme nous le détaillons dans notre article sur l'UX des applications métier.
La documentation d’exploitation : celle qu’on lit à 3 heures du matin
La documentation d’exploitation sert aux personnes qui font tourner l’application : hébergement, sauvegardes, mises à jour, incidents. C’est la plus négligée et pourtant la plus rentable.
Le livre Site Reliability Engineering de Google l’affirme sans détour : consigner à l’avance les bonnes pratiques dans un « playbook » divise environ par trois le temps moyen de rétablissement par rapport à l’improvisation. Les auteurs précisent que ces procédures ne remplacent pas des ingénieurs capables de réfléchir, mais qu’elles leur évitent de réinventer la solution sous pression.
Une documentation d’exploitation minimale comprend :
- L’installation et le déploiement : comment installer l’application de zéro sur un environnement vierge.
- La cartographie de l’hébergement : serveurs, bases, services tiers, comptes et accès (sans les mots de passe, stockés dans un coffre dédié).
- Les sauvegardes et la restauration : ce qui est sauvegardé, à quelle fréquence, et la procédure de restauration testée.
- Les procédures d’incident : que vérifier, qui prévenir, comment revenir à la version précédente.
- Les tâches récurrentes : renouvellement des certificats, purges, clôtures, mises à jour de sécurité.
- Les interfaces : chaque échange avec un autre outil (ERP, CRM, comptabilité), son sens, sa fréquence et que faire s’il échoue.
Ce dernier point est souvent oublié alors que c’est là que surviennent la plupart des incidents du quotidien, comme le montre notre article sur la synchronisation entre CRM et ERP.
La documentation pour les développeurs
Le code dit comment l’application fonctionne. Il ne dit jamais pourquoi elle a été construite ainsi. C’est ce pourquoi que la documentation technique doit conserver.
Le registre des décisions d’architecture
Un ADR (Architecture Decision Record) est une fiche courte qui consigne une décision technique importante. Le format proposé par Michael Nygard tient en cinq rubriques : un titre, le contexte (les contraintes en présence), la décision (« nous allons… »), le statut (proposée, acceptée, remplacée) et les conséquences, positives comme négatives. Les fiches sont numérotées, conservées dans le dépôt de code, et une décision abandonnée n’est jamais effacée : elle est marquée comme remplacée.
L’intérêt est très concret. Sans le contexte d’une décision, un nouveau développeur n’a que deux options : l’accepter aveuglément ou la défaire aveuglément. Les deux sont risquées.
Une vue d’ensemble de l’architecture
Inutile de produire des dizaines de schémas. Le modèle C4 de Simon Brown propose quatre niveaux de zoom : le contexte (l’application et son environnement), les conteneurs (les grandes briques déployables), les composants, et enfin le code. Pour une application de PME, les deux premiers niveaux suffisent souvent. Pour les projets plus complexes, le modèle arc42 fournit un plan en douze rubriques, des objectifs de qualité jusqu’au glossaire métier, en passant par les risques et la dette technique.
La référence technique générée
Description des API, schéma de la base, liste des variables de configuration : tout ce qui peut être produit automatiquement à partir du code doit l’être, pour ne jamais diverger. Notre article sur la documentation d’API avec OpenAPI détaille ce point.
Comment garder la documentation à jour ?
La réponse la plus efficace s’appelle « docs as code ». La communauté Write the Docs la définit comme le fait d’écrire la documentation avec les mêmes outils que le code : texte balisé simple (Markdown), gestion de versions, revue des modifications, tests automatiques.
En pratique :
- la documentation technique vit dans le même dépôt que le code ;
- une fonctionnalité n’est « terminée » que si la documentation concernée est mise à jour ;
- chaque modification de documentation est relue, comme une modification de code ;
- la documentation est publiée automatiquement à chaque version.
Ajoutez un rituel simple : une fois par trimestre, faire suivre une procédure (installation, restauration) par quelqu’un qui ne l’a jamais faite. Chaque hésitation signale une page à corriger.
La documentation, un enjeu contractuel
Pour un dirigeant, la documentation n’est pas une question de confort technique. C’est une condition de la réversibilité : la possibilité de confier l’application à une autre équipe, interne ou externe, sans repartir de zéro. Posséder le code source ne suffit pas si personne ne sait l’installer ni comprendre ses choix, comme nous l’expliquons dans notre article sur la propriété du code source et la réversibilité.
Voici la grille que nous recommandons d’annexer au contrat :
| Livrable | Public | Quand | Format conseillé |
|---|---|---|---|
| Guides utilisateurs par profil | Utilisateurs | À chaque fonctionnalité livrée | Aide en ligne, fiches, vidéos courtes |
| Procédures d’exploitation | Exploitation, support | Avant la mise en production, puis à chaque changement | Pages dans le dépôt ou le wiki interne |
| Vue d’architecture (contexte, conteneurs) | Développeurs, DSI | Dès la conception, mise à jour au fil des versions | Schémas versionnés |
| Registre des décisions (ADR) | Développeurs | À chaque décision structurante | Fiches dans le dépôt de code |
| Référence des API et interfaces | Développeurs, partenaires | Générée à chaque version | Description OpenAPI |
Exiger ces livrables dès le cahier des charges évite les discussions de fin de projet. Ils se vérifient ensuite pendant la recette, au même titre que les fonctionnalités, puis s’entretiennent dans le cadre de la maintenance.
En résumé
Une documentation qui sert vraiment est écrite pour un public précis, organisée par usage, produite au fil du projet et versionnée avec le code. Elle protège votre investissement autant que le code lui-même.
Vous préparez un projet d'application web sur mesure et voulez cadrer dès le départ ce qui doit être livré ? Décrivez votre besoin dans notre diagnostic de projet en ligne : il prend deux minutes, et nous revenons vers vous avec une première analyse.
