Vue d'ensembleUn reader pour la documentation
Un reader pour la documentation
que vous avez déjà écrite.
Pas un wiki auquel on a greffé une intégration git — l’inverse. Votre repository est la source de vérité, la structure des dossiers est la navigation, et il n’y a aucun fichier à écrire d’abord.
01
Découverte
Il sait déjà où sont vos documents
Le premier écran n'est pas un assistant de configuration. Connectez un repository et l'arborescence est là, dans un ordre que quelqu'un aurait choisi, avec des titres que quelqu'un aurait écrits.
- Où il cherche
- docs/, puis documentation/, puis doc/, puis .github/docs/ — puis les dossiers adr/, architecture/, specs/ et rfc/ à la racine, tous comme sections de premier niveau. Si aucun n’existe, il lit à la place chaque fichier Markdown du repository. Ce qu’il retient est enregistré, de sorte que les synchronisations suivantes sont déterministes.
- Ce qu’il ignore
- node_modules, .venv, vendor, target, build, dist, .next et une douzaine d’autres. Une barre latérale pleine de README de dépendances est la première chose qui donne à un outil de documentation un air d’abandon.
- Comment une page reçoit son nom
- Le titre du front matter, puis le premier H1, puis le nom de fichier rendu lisible — auth-flow.md devient Auth flow, 01-intro.md devient Intro. Un nom de fichier brut avec son extension n’est jamais affiché.
- Comment l’ordre est décidé
- README ou index en premier, et il devient la page d’accueil du dossier. Puis les préfixes numériques dans l’ordre numérique. Puis tout le reste par ordre alphabétique du titre. Les sous-dossiers après les fichiers. Aucune liste à maintenir.
- Où va le bruit
- CHANGELOG, LICENSE, CONTRIBUTING, SECURITY et leurs semblables se replient dans un groupe Fichiers du repo en bas — sauf si l’un d’eux est le seul Markdown du repository, auquel cas le masquer ne vous laisserait rien.
- La porte de sortie dont vous ne devriez jamais avoir besoin
- Il existe un fichier de surcharge. Il n’est jamais requis, il n’est mentionné nulle part dans le produit, et un repository qui en a besoin pour bien se lire est notre bug plutôt que votre tâche.
02
La surface de lecture
Conçue pour une spécification qu'on lit de bout en bout
La plupart des outils de documentation sont conçus pour le survol. Celui-ci est conçu pour la lecture de quarante minutes — une largeur de ligne qui ne bouge pas, une table des matières qui vous suit et du code qui suit le thème.
- Le chemin éclairé
- Le rail à côté de l’arborescence éclaire l’ascendance du document où vous êtes, en dégradé d’un niveau à l’autre. C’est le seul moment de spectacle visuel du produit, et il existe parce que savoir où l’on se trouve dans un corpus est précisément ce qu’une arborescence de dossiers rate d’habitude.
- Une largeur de ligne qui ne bouge pas
- Le texte est limité à 78 caractères à chaque point de rupture. Vous pouvez le changer si vous voulez une colonne plus large ou plus étroite, et ce choix vous suit.
- Sombre d’abord, clair complet
- Les deux thèmes sont conçus et non inversés, chacun avec son accent, ses propres ombres et ses six couleurs de syntaxe. Appliqué avant le premier rendu, donc aucun flash au chargement.
- Des diagrammes assortis à la page
- Mermaid lit la palette en cours au lieu d’embarquer un thème standard, et la relit quand vous changez de thème. Ni lui ni le coloriseur syntaxique n’est chargé pour un document qui n’en a pas besoin.
- Copier pour un LLM
- On ouvre souvent une spécification pour la coller ailleurs. Emportez un document ou un dossier entier en Markdown propre — front matter et badges retirés, liens relatifs réécrits — avec le nombre de tokens avant de vous décider.
03
Rester à jour
Tout le pipeline, étape par étapeLa lecture n’a pas d’étape de publication. Un push suffit.
Le repository est la source de vérité et le reste. Rien n'est copié, rien n'est importé, et fusionner est la seule chose à faire pour mettre un document à jour.
- Jamais cloné
- Un seul appel d’API renvoie toute la structure des dossiers plus un blob SHA par fichier. Pas de binaire git, pas de copie de travail, rien sur disque. Seuls les blobs Markdown sont récupérés, et rien en dehors de la racine de la documentation ne l’est jamais.
- Un fichier inchangé ne coûte rien
- Le blob SHA est le détecteur de changement. Même SHA, et le fichier est entièrement ignoré : un repository où un seul paragraphe a bougé ne fait que le travail d’un fichier.
- Un déplacement garde son identité
- Un fichier renommé est reconnu comme le même document : son état de relecture, ses notes, ses accusés de lecture et ses constats de santé le suivent. C’est la règle de correspondance exacte de git lui-même, sans score de similarité.
- Votre onglet l’apprend de la base de données
- Le worker fait le commit du changement et l’annonce sur la même connexion, dans la même transaction. Aucune boucle d’interrogation — et un document ouvert propose de se recharger au lieu d’échanger ses paragraphes sous vos yeux.
04
La couche workflow
Savoir si un document est encore vrai
Un hébergeur de documentation peut vous dire qu'une page existe. Il ne peut pas vous dire si quelqu'un est d'accord avec elle, si elle a été construite, ou si elle a cessé en silence de décrire le système.
- Deux axes, qui bougent indépendamment
- Un état de relecture — brouillon, en relecture, validé, rejeté, sans objet — et un état d’implémentation, car une spécification que tout le monde approuve et que personne n’a réalisée n’est pas la même situation qu’une spécification à moitié réalisée et contestée.
- Le décalage est une affaire de contenu, jamais de date
- Un statut retient la version exacte sur laquelle il a été posé. Modifiez le document et il affiche validé · décalé au lieu de garder un badge qui a cessé d’être vrai. Un horodatage signalerait un décalage chaque fois qu’un worker touche une ligne.
- Aucune ligne tant que personne ne décide rien
- Un document non trié n’a aucun statut et n’affiche aucune pastille. Un corpus que personne n’a regardé ne coûte rien et ressemble à ce qu’il est, plutôt qu’à un mur de brouillons.
- Des notes sur un titre
- Un retour est ancré à la section qu’il concerne. Si ce titre disparaît, la note échoue de façon visible au lieu de se déplacer sur un texte qui dit autre chose.
- Des accusés de lecture auxquels vous pouvez croire
- Comptés après dix secondes de lecture visible, jamais sur un clic dans l’arborescence, et uniquement sur la version actuelle.
- Santé de la documentation
- Liens relatifs cassés, documents dont le contenu n’a pas changé depuis trop longtemps, et documents citant un fichier source qui a changé après eux. Trois signaux vérifiables, aucune opinion, et rien qui appelle un modèle.
05
Agents
Chaque tool, et les quatre qui ne peuvent pas existerUn agent est un lecteur à part entière
Votre équipe écrit de la documentation en partie pour qu'un modèle la lise. Voici la surface qui le permet, sans copier-coller et sans lui laisser réécrire quoi que ce soit.
- Un seul endpoint, des outils retenus selon la portée
- Un endpoint MCP sans état vers lequel votre agent pointe avec une clé limitée à un projet. Une clé en lecture seule ne voit jamais les outils d’écriture — elle n’est pas simplement refusée quand elle les appelle.
- Il peut produire, pas supprimer
- Un agent dépose des artifacts dans un espace qui lui est propre, versionnés, à côté de la documentation. Il ne peut pas toucher un fichier du repository, ne peut pas supprimer un artifact et ne peut pas fermer une note.
- L’asymétrie
- Un agent peut affirmer qu’un retour est traité. Seule une personne peut le fermer. Assouplissez cela et l’objection d’un relecteur disparaît dès que l’agent affirme l’avoir traitée — en silence, à grande échelle, dans le système même qu’une équipe a adopté pour empêcher cela.
06
Accès
Rôles, équipes et invitationsRien n'est lisible par défaut
Rejoindre une organisation ne donne accès à aucun document. Cela paraît strict jusqu'à ce qu'on se rappelle que l'alternative est qu'inviter un prestataire lui donne tout l'espace de travail.
- L’adhésion, c’est l’organisation ; l’accès, c’est le projet
- Un Member lit un projet grâce à un accès d’équipe ou à un accès direct. Quelqu’un sans équipe ni accès ne lit rien du tout, et un Guest ne voit même jamais la liste des projets.
- Résolu côté serveur, à chaque requête
- Une seule requête répond à la question de savoir si vous pouvez lire quelque chose, et un projet auquel vous avez perdu l’accès répond exactement comme un projet qui n’a jamais existé. Aucune comparaison de rôles n’est jamais faite dans le navigateur.
- Les clés survivent aux personnes
- Une clé d’API appartient à l’organisation et désigne un projet, donc un job de CI ne casse pas le jour où la personne qui l’a créée change d’équipe.
- Le retrait fonctionne
- Révoquer une clé prend effet à la requête suivante. Déconnecter tous les appareils est une seule action. Déconnecter GitHub invalide les sessions qui portaient son token au lieu de les laisser fonctionner jusqu’à expiration.
Pointez-le vers un repo. Lisez le manuel que vous n’avez pas écrit.
Connectez en trois minutes. Déconnectez en un clic.