Le wiki est mort en silence
La page a été écrite après la migration, deux changements de plateforme plus tôt. Elle est toujours indexée, toujours ouverte, toujours crue. Rien ne l'a jamais marquée comme périmée.
PRODUIT DAILYOPS · DOCUMENTATION AS CODE
Une documentation qui dit quand on peut lui faire confiance.
OpsDoc génère une documentation Markdown versionnée dans Git depuis l'observation réelle de votre infrastructure : cloud, Kubernetes, Terraform, Linux, réseau, VMware, certificats, sauvegardes. Chaque document porte sa provenance, live ou mock, et un état de fraîcheur. Une porte CI échoue quand une page cesse silencieusement d'être vraie.
Trois commandes, aucun identifiant requis : init, generate, verify. Le jeu de démo montre volontairement chaque état de fraîcheur.
---id: network/fortigate-fw-01source: { provider: network, mode: live, snapshot: 8f2c-41… }freshness: { status: DRIFTED, lastVerified: 2026-10-12 }---$ ops-doc verify --ci✗ 2 documents not FRESH → build failsFreshness states7
FRESH · UNVERIFIED · SOURCE_UNAVAILABLEvisible
DRIFTED · STALE · MISSING · ERRORnever hidden
13Types de sources couverts
7États de fraîcheur
3Surfaces : CLI, API, web UI
1Source de vérité : Git
LE PROBLÈME OPÉRATIONNEL
La connaissance se dégrade quand plus personne ne sait ce qui est encore vrai.
Runbooks, notes de topologie et registres de décisions s'écartent des systèmes qu'ils décrivent. Le wiki n'est pas faux, il est invérifiable : rien sur la page ne dit s'il correspond encore à la réalité.
Personne ne possède la fraîcheur
La documentation est relue à l'écriture, puis jamais plus. Aucun mécanisme ne relie le système qui tourne à la page qui prétend le décrire.
Les audits posent l'impensable
Quand un auditeur demande la preuve qu'une procédure correspond à la production, la réponse honnête est un haussement d'épaules. La réponse malhonnête est une capture d'écran.
CE QUE OPSDOC REND POSSIBLE
Chaque page porte sa propre preuve.
OpsDoc ne vous demande pas de faire confiance à la documentation. Il fait en sorte qu'elle rende compte d'elle-même : provenance, snapshot, hash, date de vérification.
Treize sources, un pipeline
Kubernetes, états Terraform, AWS, Azure, GCP, équipements réseau via SNMP et SSH avec voisins LLDP, hôtes Linux, VMware, Windows, Active Directory, certificats TLS, jobs de sauvegarde et pages manuelles.
Sept états de fraîcheur
FRESH, DRIFTED, STALE, UNVERIFIED, SOURCE_UNAVAILABLE, MISSING et ERROR. Un mock n'est jamais présenté comme vérifié, et l'incertitude s'affiche, jamais cachée.
La porte de vérification
Verify recollecte les données live, compare le hash SHA-256 de l'observé à ce que le document avait enregistré, puis applique un TTL. En CI, une commande échoue le pipeline sur tout ce qui n'est pas FRESH.
Provenance explicite
Chaque frontmatter porte son fournisseur, son mode, live ou mock, l'identifiant de snapshot, l'horodatage et les erreurs structurées. Aucun repli silencieux, jamais.
Les humains restent dans la boucle
Les blocs générés vivent entre marqueurs, et le contexte manuel en dessous est conservé à chaque régénération. Les documents disparus sont signalés, jamais supprimés en silence.
Un graphe, pas un tas
Les relations dependsOn, runsOn et ownedBy construisent un graphe de connaissances, rendu en diagrammes de topologie D2 et en explorateur de dépendances dans l'interface web.
EN OPÉRATION
Générer. Vérifier. Commiter.
Trois commandes, des fichiers ordinaires, et un historique Git qui se lit comme un journal d'infrastructure.
Déclarez vos sources
ops-doc init écrit une configuration qui nomme vos fournisseurs : terraform, linux, network, security, backup, et les autres. Chaque source annonce live ou mock explicitement.
Générez dans Git
ops-doc generate construit un plan d'écriture, création, mise à jour ou inchangé, écrit de façon atomique, et ne touche jamais à vos sections manuelles. Dry-run d'abord, toujours.
Vérifiez avec des preuves
ops-doc verify réobserve la source, compare les hash et le TTL, et assigne à chaque document son véritable état de fraîcheur, y compris les inconfortables.
Fermez la porte du pipeline
En CI, verify --ci sort en erreur sur tout ce qui n'est pas FRESH. La documentation périmée devient un échec de build plutôt qu'un mensonge tranquille.
POURQUOI C'EST DIFFÉRENT
Des fichiers ordinaires, une honnêteté rare.
OpsDoc ne remplace ni Git, ni un CMDB, ni votre wiki. C'est un pipeline documentaire bâti autour de fichiers que vous pouvez diff, relire et commiter.
Git est la source de vérité
Les documents vivent sous content/docs en Markdown brut avec frontmatter YAML. La base SQLite n'est qu'un index et un cache. Vous pouvez partir, et tout emporter.
- Lisible, diffable, relu dans n'importe quelle merge request
- La base est un cache, Git est le contrat
- Export HTML pour les remises d'audit hors ligne
L'incertitude comme état de première classe
La plupart des outils ont deux états : à jour et cassé. OpsDoc en a sept, parce que la réalité aussi. Une source injoignable le dit sur la page elle-même.
- UNVERIFIED : données mock ou source non déclarée
- SOURCE_UNAVAILABLE : le fournisseur était injoignable
- MISSING : la ressource a disparu d'un snapshot live, le doc est gardé et signalé
La conformité depuis les mêmes fichiers
Les mappings NIS2 et ISO 27001 sont scorés depuis la documentation elle-même, avec les identifiants de documents comme preuves. Le tableau de bord de l'UI est généré, pas maintenu.
- Les liens de preuve pointent vers de vrais commits
- Pas d'univers documentaire parallèle pour les audits
- La piste d'audit, c'est l'historique Git
SÉCURITÉ
Un pipeline qui respecte la production.
OpsDoc touche vos systèmes pour les lire. Il est construit pour le faire sûrement, et pour prouver ce qu'il a vu.
API en loopbackMutations par bearer tokenRedaction des secretsConfinement des cheminsÉcritures atomiquesSessions localesErreurs structuréesAucun repli silencieux
Lire est léger, écrire est gardé
L'API écoute sur loopback par défaut, les mutations exigent un bearer token, et le générateur écrit via des fichiers temporaires renommés atomiquement : aucun lecteur ne voit jamais une page à moitié écrite.
Aucun secret n'entre dans le registre
Une couche de redaction retire les identifiants des données collectées avant toute écriture dans un document ou la base. Ce qu'OpsDoc stocke est sûr à commiter par construction.
Confinement des chemins
Le générateur ne peut pas écrire hors de sa racine déclarée, et les évasions par symlink sont bloquées. Les limites de votre dépôt sont appliquées, pas supposées.
ÉTAT DU SYSTÈME
Où en est OpsDoc aujourd'hui.
OpsDoc est un prototype de recherche, version 0.1. La promesse centrale, génération fidèle et fraîcheur honnête, est implémentée et testée. La collecte live est progressive.
Pipeline de génération, sept états de fraîcheur, porte verify en CI, graphe de connaissances et topologie D2, interface web avec documents, tableau de fraîcheur, vues réseau et tableau de conformité. La collecte live fonctionne pour Terraform, Linux via SSH, réseau via SNMP avec LLDP, certificats TLS, VMware, Windows, AD et jobs de sauvegarde.
Les collecteurs AWS, Azure, GCP et Kubernetes tournent en mode mock. Les exports au-delà du HTML (PDF, Confluence) sont des stubs, et il n'y a pas d'ordonnanceur interne : la vérification tourne dans votre CI, par conception.
OpsDoc explore ce que devient la documentation quand on la traite comme une partie active et responsable des opérations. Route : collecteurs cloud live, invalidation événementielle, et exercices de vérification de runbooks.
QUESTIONS
Réponses franches.
OpsDoc remplace-t-il notre wiki ou CMDB ?
Non. Il les alimente. OpsDoc génère une documentation avec preuve de fraîcheur que vous pouvez publier partout. Les wikis gardent la prose ; OpsDoc garantit les parties qui prétendent décrire la réalité.
Que signifie exactement UNVERIFIED ?
Le document a été généré depuis des données mock, ou son fournisseur n'est pas déclaré dans la configuration. Il s'affiche avec son statut visible, parce que cacher l'incertitude serait pire.
Comment l'essayer sans accès production ?
Réglez OPS_DOC_MOCK=1, lancez generate puis verify. Le jeu de démo livré contient volontairement chaque état de fraîcheur, dont un document délibérément dérivé que le vérificateur attrape.
Où vit la documentation ?
Dans votre dépôt, sous content/docs, en Markdown ordinaire avec frontmatter YAML. Vous la relisez en merge request, et l'historique Git est la piste d'audit de votre documentation.
Pourquoi pas d'ordonnanceur intégré ?
Parce que la vérification appartient là où vit déjà votre pipeline. Lancez ops-doc verify --ci en CI, et la documentation périmée échoue le build. L'outil reste honnête, le processus reste le vôtre.
Faites répondre la documentation d'elle-même.
Clonez le dépôt et lancez la démo en trois commandes, ou parlons de brancher OpsDoc sur un environnement réel.
Lancer la démo Nous écrire OpsDoc assume son statut de prototype de recherche. Les premiers collaborateurs dessinent la feuille de route.