La documentation fait partie du produit

Beaucoup d’équipes parlent encore de la documentation comme si elle ne commençait qu’après le vrai travail. On construit d’abord le produit, puis quelqu’un écrit ce qui s’est passé. Ce modèle était déjà faible avant le développement assisté par l’IA. Avec l’IA, il devient un vrai risque.

Lorsque le code, le texte, les interfaces et les flux de travail peuvent être générés très vite, la documentation n’est plus seulement une couche tardive. Elle devient une partie du mécanisme qui garde le produit cohérent.

Pourquoi cela compte encore plus aujourd’hui

L’IA peut générer une implémentation à partir d’une intention incomplète. Cela est souvent présenté comme une commodité. En pratique, cela signifie que chaque ambiguïté du projet devient un endroit où le produit peut dériver.

Si la documentation est faible ou dépassée, des personnes et des outils différents déduiront des produits différents à partir du même dépôt.

Un contributeur peut suivre l’interface utilisateur actuelle. Un autre peut suivre un ancien README. Un assistant IA peut suivre le fichier le plus proche et inventer le reste.

Le problème n’est pas seulement la justesse au niveau du code. Le problème est de savoir si le projet décrit encore un seul produit plutôt que plusieurs suppositions qui se chevauchent.

La documentation remplit quatre fonctions produit

Une bonne documentation fait bien plus qu’expliquer l’interface après coup.

Premièrement, elle porte l’intention. Elle dit aux futurs contributeurs ce que le produit essaie d’accomplir et ce qu’il n’essaie explicitement pas de devenir.

Deuxièmement, elle fixe des attentes. Les lecteurs peuvent voir ce qui existe maintenant, ce qui est prévu et ce qui ne devrait pas être décrit comme déjà implémenté.

Troisièmement, elle réduit le coût de coordination. Nouveaux contributeurs, relecteurs, institutions et assistants IA peuvent tous s’orienter sans reconstruire le projet à partir de fragments.

Quatrièmement, elle soutient la confiance. Un projet qui sépare clairement l’état actuel, la direction prévue et le flux de travail expérimental est plus facile à évaluer et plus facile à maintenir.

Let Books est déjà structuré ainsi

Le dépôt Let Books démontre déjà cette approche à plusieurs couches.

• AGENTS.md définit le but du produit, les flux de travail, les frontières du domaine et la direction à long terme.
• AGENTS-Implementation.md définit les règles tactiques d’implémentation et de documentation.
• README.md explique l’état actuel du dépôt et distingue les livrables présents des plans futurs.
• docs/ définit une plateforme de connaissance avec des conventions de publication, d’écriture, de localisation et de cartographie des sources.

Cela signifie que la documentation ici n’est pas seulement une explication. Elle fait partie de la manière dont le projet fonctionne.

Une documentation périmée est une dette produit

Les équipes reconnaissent souvent la dette technique seulement quand elle apparaît dans le code. Mais une documentation périmée crée une forme similaire de friction.

Une documentation périmée conduit à :

• de mauvaises hypothèses d’implémentation
• la répétition de décisions déjà prises
• des démos qui deviennent accidentellement la vérité produit
• une intégration plus lente de nouveaux contributeurs
• des revues plus difficiles parce que le standard n’est pas clair

Dans les flux soutenus par l’IA, cette dette s’accumule encore plus vite, parce que les assistants poursuivent très bien à partir d’hypothèses proches, même lorsqu’elles sont dépassées.

Documentation et implémentation doivent former une chaîne

Le bon modèle n’est pas un schéma rigide « documentation d’abord, code ensuite ». Le bon modèle est une chaîne entretenue :

• les spécifications définissent l’intention
• les documents d’état actuel expliquent ce qui existe maintenant
• la démo et l’implémentation rendent le flux concret
• les tests et la validation vérifient les attentes
• la CI rend la dérive visible

Si un maillon change, ceux qui l’entourent doivent aussi être revus.

Pourquoi un public plus large devrait aussi s’en soucier

Ce n’est pas seulement une question technique.

Les institutions devraient s’en soucier parce que la documentation influence la gouvernance, la confiance dans les achats, l’intégration, la continuité et l’auditabilité.

Les étudiants devraient s’en soucier parce que documenter l’intention fait partie de l’apprentissage de la construction de systèmes fiables, et non d’un supplément administratif.

Les lecteurs plus généraux devraient s’en soucier parce qu’un produit doté d’une documentation claire est généralement aussi un produit fondé sur des décisions plus claires.

Le test pratique

Une question utile pour toute équipe est simple :

Si un nouveau contributeur ou un assistant IA entrait aujourd’hui dans le dépôt, les documents l’aideraient-ils à construire le produit voulu, ou surtout quelque chose qui paraît plausible ?

Cette différence est la différence entre une documentation comme commentaire et une documentation comme partie du produit.

La leçon durable

La documentation n’est pas séparée de la qualité du produit.

Elle façonne l’implémentation, la revue, la communication, la validation et la confiance à long terme. Dans les projets soutenus par l’IA, la documentation fait partie du produit parce qu’elle fait partie du système qui empêche la dérive du produit.

Lectures liées

• ../../wiki/documentation-traceability.md
• ../../wiki/validation-layers.md
• ai-as-an-oracle.md
• spec-driven-development-in-let-books.md