Documentation pilotée par README et LLM Wiki

Idée centrale

Une documentation pilotée par README et un LLM Wiki reposent sur une base commune : des connaissances lisibles, proches du travail, versionnées et accessibles par routage progressif. Elles diffèrent surtout par l’unité de connaissance, les sources mobilisées et la responsabilité de maintenance.

SRC-2026-005 compare ces deux approches à partir d’un retour d’expérience logiciel. Cette page en reconstruit les critères sans transformer ses conventions locales en règles universelles.

Fondation commune

Les deux approches peuvent partager :

des fichiers texte inspectables ;
une organisation explicite ;
un fichier d’instructions qui route vers la documentation ;
une lecture progressive limitée aux éléments pertinents ;
une mise à jour liée aux changements du système ;
un historique et une revue.

Le fichier de règles agit comme un routeur, pas comme un conteneur exhaustif de connaissances.

Comparaison

Dimension	Documentation par README	LLM Wiki
unité principale	module, service ou sujet possédé par une équipe	connaissance transversale ou synthèse multi-source
auteur principal	développeur ou équipe responsable	modèle sous gouvernance humaine
sources	code et contexte immédiat du module	README, code, historique, décisions, incidents et autres sources admises
structure	généralement définie à l’avance	peut évoluer avec les concepts et relations
mise à jour	avec le changement de code et sa revue	ingestion ou synchronisation ciblée, puis audit
portée	projet et responsabilités locales	relations entre modules, systèmes ou corpus hétérogènes
source de vérité	documentation collective versionnée	couche canonique selon sa gouvernance ; parfois synthèse personnelle dérivée
risque principal	dérive manuelle et silos par module	synthèse erronée, duplication ou divergence non revue

Routage progressif

Un fichier d’instructions peut établir :

les règles générales ;
un ordre de lecture ;
des correspondances entre type de tâche et document ;
une délégation vers le README ou la page pertinente.

Le même principe s’applique à l’index d’un wiki : commencer par la carte, sélectionner quelques pages candidates, puis suivre les relations nécessaires. Le nombre de pages et la profondeur doivent être adaptés au risque et à la complexité, non copiés depuis une implémentation particulière.

Quand les README peuvent suffire

Une documentation de dépôt bien structurée peut être suffisante lorsque :

les limites des modules sont claires ;
chaque connaissance appartient naturellement à une équipe ou un composant ;
les décisions et flux transversaux disposent déjà de documents dédiés ;
les mises à jour documentaires accompagnent les modifications de code ;
le moteur de recherche retrouve correctement les fichiers pertinents.

Dans ce cas, créer un wiki séparé peut ajouter une couche de maintenance sans bénéfice démontré.

Quand le wiki devient utile

Une couche de wiki est justifiée lorsque les réponses importantes exigent :

de relier plusieurs modules ou contextes ;
de comparer plusieurs fournisseurs ou variantes ;
de conserver des contradictions ;
de synthétiser code, décisions, historique et sources externes ;
de maintenir des connaissances qui n’ont pas de propriétaire documentaire unique.

Synthèse éditoriale : la complexité transversale est un meilleur déclencheur que la taille brute du dépôt.

Coexistence et autorité

Un wiki personnel ou expérimental ne doit pas remplacer silencieusement la documentation d’équipe. Les README et décisions versionnés peuvent rester les références collectives, tandis que le wiki sert de couche de synthèse.

Lorsqu’une connaissance du wiki doit devenir normative pour l’équipe, elle doit être promue vers la documentation partagée ou soumise à une politique de revue équivalente. Cette règle complète la Gouvernance humaine des modifications par LLM.

Fraîcheur

Deux mécanismes sont complémentaires :

mettre à jour le README dans la même modification que le code ;
rattacher une page synthétique à la révision des sources qu’elle décrit, puis examiner le différentiel avant de déplacer cette révision.

Une empreinte ou une révision identique prouve la stabilité de l’artefact comparé, pas la vérité de l’interprétation. Voir Provenance structurelle des connaissances.

Progression possible

Synthèse éditoriale :

commencer par un README utile et un fichier de règles qui route ;
ajouter une arborescence de documents pour l’architecture, les décisions, modules et intégrations ;
créer un wiki sur le sous-système où les connaissances importantes restent dispersées ;
étendre seulement après mesure des bénéfices et du coût de maintenance.

Cette progression n’impose aucun seuil de fichiers ou de pages.

Erreurs fréquentes

Charger toute la documentation dans le fichier d’instructions.
Dupliquer les README dans le wiki sans synthèse nouvelle.
Traiter un wiki personnel comme une règle d’équipe.
Déduire une décision historique uniquement à partir du code actuel.
Supposer qu’une mise à jour automatique est nécessairement juste.
Adopter des budgets de pages ou profondeurs de liens sans mesure locale.

Limites et nuances

La comparaison provient d’un seul retour d’implémentation. Le dépôt, le wiki et les mesures ne sont pas disponibles dans le corpus. La page décrit donc un cadre de décision et non une supériorité démontrée d’une approche.

Relations

LLM Wiki
Pipeline incrémental d’intégration documentaire
Provenance structurelle des connaissances
Contrôle de santé d’un wiki vivant
Gouvernance humaine des modifications par LLM
Mise à l’échelle d’un LLM Wiki

Sources

Source interne : SRC-2026-005