Séparer le code de sa documentation

Le réflexe est de tout garder ensemble : le code d'une application projetA-app, et sa documentation dans le même dépôt — un README, un dossier /docs, des commentaires. C'est commode, et c'est un piège à l'échelle d'un projet qui dure. Le pattern défendu ici est inverse : la documentation de production d'une application vit dans un dépôt distinct, projetA-doc. Ce texte explique pourquoi ce découplage n'est ni de la bureaucratie ni de la duplication, mais l'endroit où chaque information vit le mieux.

Deux cycles de vie qui ne battent pas au même rythme

Le code bouge à la vitesse des features : plusieurs commits par jour, des branches, des refactors, du bruit permanent et normal. La documentation de production — les spécifications fonctionnelles, les spécifications techniques, les recettes de test — a une autre cadence : elle se stabilise, se relit, se canonise. Elle change quand l'intention change, pas quand une variable est renommée.

Coller les deux dans un même dépôt les force à partager une histoire git qu'ils ne veulent pas partager. Le flot de commits du code noie les rares changements de doc ; inversement, une refonte documentaire pollue l'historique du code. On perd la lisibilité des deux. Séparer les dépôts, c'est simplement reconnaître que deux artefacts à deux cadences méritent deux lignes de temps.

Chaque fichier a déjà un rôle — la doc en est un autre

Un dépôt de code n'est pas dépourvu d'écrit, et ce n'est pas le sujet. Le README amorce : il dit comment démarrer, où regarder. Le changelog raconte l'historique : ce qui a changé, version par version. Un commentaire explique une ligne : le pourquoi local d'un choix que le code seul ne dit pas. Chacun a un rôle borné, et le tenir dans ses limites est déjà une discipline.

La documentation du projet — le quoi et le pourquoi fonctionnels, l'architecture technique, les contrats — n'est aucun de ces trois-là. La forcer dans un README qui gonfle, ou dans un /docs interne qui se désynchronise, c'est demander à un artefact de jouer un rôle qui n'est pas le sien. Le dépôt de doc distinct n'ajoute pas une couche : il donne un lieu propre à une information qui, sinon, squatte les autres.

L'anti-biais de l'initié

Une documentation écrite dans le dépôt du code tend à être écrite par celui qui a le nez dans le code. C'est le biais d'initié : on documente ce qu'on croit évident parce qu'on le connaît trop bien, on saute les marches qu'un lecteur extérieur ne franchit pas, on décrit l'implémentation là où il fallait décrire l'intention. Le résultat est fidèle au code du jour et illisible pour qui arrive.

Un dépôt de doc distinct autorise une rédaction à distance du code — un autre regard, un autre moment, parfois une autre main. Cette distance n'est pas un luxe : c'est ce qui restaure la question de l'étranger compétent — « qu'est-ce que ce projet fait, et pourquoi ? » — au lieu de « qu'est-ce que cette classe fait ». La séparation physique rend l'anti-biais structurel plutôt que dépendant de la bonne volonté.

Une doc séparée devient exploitable

Le bénéfice décisif est le dernier. Un dépôt de doc homogène et séparé peut être projeté vers un corpus interrogeable — indexé pour une recherche sémantique, servi à un assistant. Une doc éparpillée dans des README, des commentaires et des dossiers internes ne le permet pas : il n'y a rien de cohérent à ingérer, juste des fragments noyés dans du code.

Reste une frontière à ne jamais oublier. La doc de production reste privée : elle décrit la configuration réelle et n'a pas vocation à sortir telle quelle. Ce n'est pas elle qu'on indexe publiquement, mais une projection filtrée — un sas qui ne laisse passer que la méthode, jamais les valeurs réelles. Le découplage code/doc rend cette projection possible ; l'airlock la rend sûre. Les deux disciplines se complètent.

Ce que ce n'est pas

Séparer n'est pas dupliquer : l'information n'existe qu'à un seul endroit, celui où elle vit le mieux ; on ne recopie pas le code dans la doc. Ce n'est pas non plus de la bureaucratie : aucun formulaire, aucune cérémonie ajoutée, juste un rangement qui rend chaque artefact plus lisible et plus utile. Le pattern tient en une phrase : donner à chaque information son lieu propre, et faire de ce lieu quelque chose d'exploitable.