Documentation technique site web

Personne ne réclame la documentation technique tant que l'équipe en place répond au téléphone. Elle devient le premier sujet le jour où elle ne répond plus.

Alexandre Associé, architecture et développement back

Publié le 13 octobre 2021

Mis à jour le 28 août 2026

Lecture 7 minutes

La documentation technique décrit comment un site est construit : les technologies, les versions, l’architecture, les dépendances et les accès. Elle ne s’adresse pas aux utilisateurs, mais à celui qui reprendra le code.

À quoi elle sert concrètement

Trois situations la rendent indispensable, et elles arrivent toutes tôt ou tard.

Le changement d’intervenant. Développeur qui part, prestataire qu’on remplace, équipe interne qui reprend un projet externalisé. Sans documentation, la première semaine passe à lire du code au lieu de produire.
La montée de version. Savoir quelle version de PHP, de framework ou de bibliothèque est en place détermine si une mise à jour est une formalité ou un chantier.
L’incident. À trois heures du matin, la question n’est pas comment le site fonctionne, mais où sont les accès, où tournent les tâches planifiées et comment restaurer.

Ce qu’elle contient

Le contenu varie avec le projet, mais un socle revient toujours.

L’architecture : les composants, leurs rôles, ce qui parle à quoi.
Le schéma de base de données, avec les relations et les champs dont le nom ne suffit pas à comprendre l’usage.
Les dépendances et leurs versions : framework, bibliothèques, extensions, avec ce qui a été modifié par rapport à la version d’origine.
Les environnements : production, préproduction, local, et ce qui diffère entre eux.
La procédure de mise en production, écrite pour être suivie par quelqu’un qui découvre le projet.
Les tâches planifiées et les traitements automatiques, souvent invisibles et toujours oubliés.
La documentation des API exposées ou consommées, avec les modes d’authentification.
La sauvegarde et la restauration : où, à quelle fréquence, et comment on restaure réellement.

Les identifiants n’y figurent pas. La documentation dit où ils sont rangés, elle ne les contient pas.

Quand la rédiger

Pendant le développement, pas après. Écrite au fil de l’eau par ceux qui construisent, elle coûte quelques heures réparties sur le projet. Reconstituée a posteriori, elle demande de relire le code pour retrouver des décisions dont personne ne se souvient.

Le réflexe qui fonctionne : toute décision technique qui a fait hésiter mérite une ligne expliquant pourquoi cette option a été retenue. C’est ce qui manque le plus souvent, et c’est ce qui coûte le plus cher à redécouvrir.

La maintenir

Une documentation fausse est pire qu’une documentation absente : elle inspire confiance et envoie sur une mauvaise piste. Deux règles suffisent. Elle vit dans le dépôt de code, versionnée avec lui, pas dans un traitement de texte partagé. Et sa mise à jour fait partie de la tâche, pas d’un chantier de fin de projet qui n’arrive jamais.

Ce qu’elle n’est pas

Elle ne remplace pas la documentation utilisateur, qui décrit les parcours et les écrans pour ceux qui se servent de l’outil. Elle ne remplace pas non plus le cahier des charges, qui dit ce que le site doit faire avant qu’il existe. Les trois documents se complètent et ne couvrent pas les mêmes besoins.

Sur les projets de développement web que nous reprenons, l’état de cette documentation est le premier indicateur de ce que coûtera la reprise.

Avant de signer avec un prestataire, demandez à voir un exemple de documentation technique livrée sur un projet précédent. C’est un test simple et révélateur : une agence qui n’en produit pas vous laissera dépendant d’elle, ce qui n’est pas toujours involontaire.

Questions fréquentes

Questions fréquentes sur la documentation technique

Qui l’écrit, ce qu’elle coûte, et ce qui arrive sans elle.

Les développeurs qui construisent le site, pendant qu’ils le construisent. Un rédacteur extérieur peut mettre en forme, il ne peut pas documenter des décisions auxquelles il n’a pas assisté. Côté client, la seule action utile est de l’exiger dans le contrat et de vérifier sa livraison.

La documentation technique s’adresse à celui qui modifie le site : architecture, versions, dépendances, déploiement. La documentation utilisateur s’adresse à celui qui s’en sert : écrans, parcours, actions possibles. Deux publics, deux documents, aucun ne remplace l’autre.

Dans le dépôt de code, à côté de ce qu’elle décrit, pour être versionnée avec lui. Un document isolé dans un espace partagé se désynchronise en quelques semaines sans que personne s’en aperçoive.

La reconstituer entièrement coûte cher pour un bénéfice différé. Le compromis raisonnable consiste à documenter d’abord ce qui sert en cas d’urgence : accès, hébergement, procédure de restauration, tâches planifiées. Le reste s’écrit au fil des interventions suivantes.

Non. La documentation indique quels accès existent et où ils sont conservés, dans un gestionnaire de secrets ou un coffre partagé. Des identifiants écrits dans un document versionné se retrouvent dans l’historique du dépôt, définitivement.

Alexandre

Associé, architecture et développement back

Associé et architecte back, il travaille en Symfony sur des outils métier, des API et des extranets où la logique et les droits pèsent plus lourd que l'affichage. Il intervient aussi sur la reprise de bases de code héritées. Son terrain de prédilection : l'architecture des projets complexes, là où la structure décide de tout le reste.

À lire ensuite