Six services, six ensembles de notes,
et aucun moyen de les lire ensemble.
Les notes existent. Chaque service a un README qui vaut la lecture, la plupart ont un dossier d’architecture, et quelqu’un a écrit un document vraiment bon sur le fonctionnement du flux de paiements. Il est dans un repository que vous n’avez pas cloné.
Chaque outil capable de présenter cela vous demande de choisir un repository et d’écrire un fichier de navigation pour lui. Ce modèle a été conçu pour un produit doté d’un seul site de documentation, et il ne convient pas à une équipe plateforme avec trente repositories et aucune envie d’écrire trente fichiers de configuration.
Alors le savoir reste là où il a été écrit, se retrouve par grep, si tant est qu’il se retrouve, et se reconstitue en réunion tous les quelques mois par ceux qui étaient là la fois précédente.
Le multi-repository est la partie difficile à copier sur le plan de l’architecture : « un repository, un site » est une hypothèse ancrée jusqu’au fond de chaque outil conçu pour la documentation publique.
Les parties qui comptent ici
Pas toute la liste des fonctionnalités — celles dont dépend ce problème précis.
Plusieurs repositories, un seul espace de travail
Un projet contient autant de repositories que vous lui en confiez. L’arborescence les montre ensemble, la recherche les couvre tous en une seule requête, et l’accès s’accorde une fois au niveau du projet plutôt que par repository.
La structure des dossiers est la navigation
Trente repositories, c’est trente fichiers de navigation dans n’importe quel autre outil. Ici, c’est trente connexions et aucune configuration, car la structure que vous avez déjà est celle que nous lisons.
La documentation en retard sur le code
Une note qui cite un chemin source modifié après elle devient un constat. À l’échelle d’une plateforme, c’est la différence entre savoir que votre documentation d’architecture a dérivé et le découvrir pendant une panne.
Des diagrammes assortis à la page
Mermaid s’affiche dans la palette active du produit plutôt que dans un thème standard, et la relit quand vous changez de thème. Un diagramme de séquence dans une note d’architecture, c’est la raison d’être de la note.
Des agents qui citent au lieu de deviner
Un agent de code qui travaille sur un service peut lire ce que les cinq autres ont documenté, avec une URL qu’une personne peut ouvrir — au lieu de déduire votre architecture du code qu’il se trouve avoir en contexte.
Un déplacement garde son identité
Réorganiser la documentation entre repositories est courant dans une équipe plateforme. Un fichier renommé ou déplacé reste le même document : son état de relecture, ses notes et ses constats de santé le suivent au lieu d’être perdus sans bruit.
Ce qui se passe réellement
- 01Connectez les services un par unChacun prend environ une minute et ne demande aucune configuration. Regroupez-les dans un projet nommé d’après le domaine plutôt que d’après le repository.
- 02L’arborescence se construit d’elle-mêmeRacines de documentation trouvées par repository, titres déduits, ordre appliqué, CHANGELOG et LICENSE repliés à l’écart. Personne n’écrit de barre latérale.
- 03La recherche n’est plus par repositoryUne seule touche pour chercher dans tous les services de l’organisation, avec un classement, le chemin et l’état de relecture à côté de chaque résultat.
- 04Accordez le projet à une équipe, une foisL’accès, c’est le projet, pas le repository : intégrer quelqu’un à la plateforme demande un seul accès plutôt que trente.
- 05Branchez-y vos agentsUne clé limitée à ce projet, en lecture seule, avec en option un seuil de relecture pour qu’un agent ne voie que les documents que quelqu’un a validés.
- 06Voyez le code s’éloigner des notesLes pushes qui touchent des chemins source cités par vos documents deviennent des constats. C’est le seul signal automatique du produit qu’un humain n’a pas eu à signaler.
Ce que cela ne résout pas
Chaque page de ce site en porte une, pour la même raison : une page de cas d'usage sans limite est une brochure.
- Il ne lit pas votre code
- Rien en dehors de la racine de documentation n’est jamais récupéré. Nous voyons les noms des chemins source modifiés dans la charge utile du push — jamais leur contenu —, ce qui rend le signal de retard sur le code peu coûteux et ce qui le limite aussi.
- Il ne génère pas de diagrammes
- Le Mermaid que vous avez écrit s’affiche correctement. Il n’y a aucune déduction d’architecture à partir d’un graphe de dépendances, et il n’y en aura pas.
- Une organisation, pas une fédération
- Les repositories se regroupent en projets au sein d’une organisation. Lire deux organisations distinctes depuis une même vue n’est pas quelque chose que ce produit fait.