Living Documentation: When Knowledge Becomes a Neural Network
The Documentation Problem
Most documentation dies the moment it’s written.
You’ve seen it. A README file created with the best intentions. Complete, thorough, accurate… for exactly one day. Then the code changes. The architecture evolves. The examples become outdated.
Six months later, that documentation is worse than useless - it’s actively misleading.
The traditional solution? “Documentation as code.” Version control. Review processes. Automation. These help, but they treat the symptom, not the disease.
The real problem: Documentation is treated as a static artifact, not a living entity.
What If Documentation Could Think?
Here’s what I discovered while building Cortex:
Documentation isn’t files. It’s a knowledge graph.
Every concept connects to other concepts. Every implementation references patterns. Every guide assumes prerequisite understanding. These aren’t isolated documents - they’re nodes in a network.
And when you treat them that way, something remarkable happens:
The documentation becomes self-organizing.
The Living Documentation Network
Look at what happens when documentation lives in a network:
1. Documents Connect Automatically
When I write about MCP server architecture, the system sees:
- References to “Kubernetes deployment”
- Mentions of “Claude API integration”
- Links to “GitOps patterns”
Each reference is a connection. Not a hyperlink someone manually added - an emergent relationship the system discovered.
The network builds itself.
2. Changes Propagate
When the GitOps deployment pattern changes:
- All MCP server docs that reference it light up
- Guides that assume the old pattern get flagged
- Examples that need updates become visible
The knowledge flows through the network.
3. Gaps Become Obvious
When I add a new MCP server:
- The network sees it lacks a setup guide
- It notices references from other docs with no destination
- It identifies which templates apply
Missing documentation stands out because the network is incomplete.
4. Redundancy Gets Eliminated
When three different docs explain the same concept:
- The network recognizes semantic similarity
- It suggests consolidation
- It creates a canonical reference
Knowledge converges naturally.
How It Works: The Architecture
The living documentation system has three layers:
Layer 1: Document Ingestion
Every markdown file, README, ADR, and guide gets parsed for:
- Concepts (nouns, technical terms, patterns)
- Relationships (references, dependencies, examples)
- Context (which domain, what purpose, who uses it)
This creates a semantic map of the documentation.
Layer 2: Connection Discovery
The system doesn’t just index - it understands.
Using embeddings and semantic analysis:
- Similar concepts cluster together
- Related patterns link automatically
- Implicit dependencies surface
You write “This deploys to k3s” and the network connects it to:
- k3s architecture docs
- ArgoCD deployment patterns
- Namespace design guides
- Resource quota policies
Without you specifying any of those links.
Layer 3: Knowledge Synthesis
The real magic: the network doesn’t just store knowledge - it generates it.
When you ask: “How do I deploy a new MCP server?”
The system:
- Identifies all MCP server deployments
- Extracts the common pattern
- Notes the variations (different resource requirements, ingress configs, secrets)
- Synthesizes a new guide that’s current, complete, and contextualized
The documentation writes itself.
What This Looks Like in Practice
Before: Static Documentation
docs/
├── mcp-servers/
│ ├── sandfly-mcp-server.md (outdated)
│ ├── talos-mcp-server.md (missing deployment steps)
│ └── unifi-mcp-server.md (duplicates sandfly setup)
├── kubernetes/
│ └── deployment-guide.md (doesn't mention MCP)
└── gitops/
└── argocd-patterns.md (examples broken)Problem: Every file is an island. Finding what you need requires:
- Knowing it exists
- Searching manually
- Cross-referencing multiple docs
- Hoping they’re all current
After: Living Network
Ask: “Show me how to deploy the Proxmox MCP server”
The network:
- Finds the Proxmox MCP server concept
- Connects it to Kubernetes deployment patterns
- References ArgoCD GitOps workflow
- Notes specific requirements (Proxmox API credentials)
- Synthesizes a complete, current guide
Everything is connected. Nothing is hidden.
The Self-Healing Property
Here’s where it gets interesting.
Traditional documentation requires human maintenance:
- Someone notices it’s outdated
- Someone updates it
- Someone reviews the changes
- Someone merges the PR
Living documentation is self-healing:
Example: API Endpoint Change
The system detects:
Code: POST /v2/tasks (new endpoint)
Docs: Reference to POST /v1/tasks (old endpoint)What happens:
- Alert: Documentation drift detected
- Analysis: 12 documents reference old endpoint
- Synthesis: Generate migration guide
- Update: Patch affected documents
- Verification: Confirm all links resolve
From detection to fix: automated.
The Emergent Intelligence
After running this system for Cortex, I’ve noticed patterns I didn’t design:
Pattern 1: Concept Clustering
Documents about related topics naturally cluster in the network:
- All security docs connect densely
- Infrastructure guides form their own cluster
- MCP servers link to both clusters as bridges
The knowledge graph reflects the actual architecture without anyone explicitly modeling it.
Pattern 2: Authority Emergence
Some documents become hubs:
- The GitOps deployment guide gets referenced everywhere
- The MCP server template is a central pattern
- The Kubernetes architecture doc anchors the cluster
These aren’t marked as “authoritative” - they earn centrality through connections.
Pattern 3: Knowledge Flows
When a core concept changes:
- Updates propagate outward through connections
- Dependent docs get flagged
- Examples automatically update
- Guides stay synchronized
The network maintains its own consistency.
Pattern 4: Gap Detection
The system identifies missing documentation by analyzing:
- Code that lacks corresponding docs
- References to non-existent guides
- Clusters with weak internal connections
- Concepts mentioned but never defined
The network knows what it doesn’t know.
The Meta Layer: Documentation About Documentation
The living network generates meta-documentation automatically:
Knowledge Map
A visual representation of how concepts connect. You can see:
- Which topics are well-documented (dense clusters)
- Which areas are sparse (weak connections)
- Which docs are central (high connectivity)
- Which concepts are isolated (orphan nodes)
Documentation Health Metrics
- Coverage: % of code with corresponding docs
- Freshness: Average age of references
- Connectivity: Links per document
- Completeness: Concepts defined vs concepts referenced
Learning Paths
The network can generate guided learning sequences:
Want to understand MCP servers?
- Start with Kubernetes basics
- Learn ArgoCD GitOps patterns
- Study MCP protocol spec
- Deploy your first server
- Explore advanced routing
The path emerges from the network structure.
The Power of Self-Organization
Traditional documentation requires:
- Careful information architecture
- Manual taxonomy management
- Constant reorganization
- Human judgment on structure
Living documentation organizes itself:
- Concepts cluster by semantic similarity
- Important docs naturally become hubs
- Related information links automatically
- Structure emerges from relationships
This isn’t chaos - it’s emergent order.
Like a neural network, the structure reflects the actual patterns in the knowledge, not someone’s preconceived hierarchy.
What This Enables
1. Instant Onboarding
New team member asks: “How does Cortex work?”
The network generates a personalized learning path based on:
- Their background (detected from questions)
- Their goals (what they need to build)
- Their progress (what they’ve already read)
Custom onboarding guide, synthesized on-demand.
2. Context-Aware Answers
Instead of searching for docs, you ask questions:
“How do I debug a failing MCP server?”
The system:
- Identifies the failing server from context
- Pulls relevant troubleshooting guides
- Cross-references common issues
- Synthesizes a debugging plan
The answer is always current and complete.
3. Proactive Documentation
When the system detects:
- New code without docs
- Patterns being repeated
- Common questions emerging
- Knowledge gaps
It generates documentation automatically.
You don’t write docs about the new MCP server - the network analyzes the deployment, extracts the pattern, and documents it.
4. Living Runbooks
Operations guides that update themselves:
- Incident response procedures stay current
- Troubleshooting steps reflect latest infrastructure
- Contact information remains accurate
- Prerequisites automatically link
The runbook is always ready.
The Technical Implementation
How does this actually work?
Stage 1: Semantic Indexing
Every document gets:
- Embedded (vector representation)
- Chunked (concept-level granularity)
- Linked (explicit and implicit references)
- Contextualized (domain, purpose, audience)
This creates a semantic search index over all documentation.
Stage 2: Connection Discovery
Using:
- Cosine similarity for concept clustering
- Named entity recognition for cross-references
- Dependency analysis for prerequisite detection
- Citation tracking for authority ranking
The system builds a knowledge graph.
Stage 3: Knowledge Synthesis
When asked a question:
- Embed the query (same vector space as docs)
- Find relevant nodes (semantic search)
- Traverse connections (explore the graph)
- Synthesize response (LLM-generated from context)
The answer draws from the entire network, not isolated docs.
Stage 4: Continuous Learning
As the system runs:
- User interactions improve relevance ranking
- Update patterns train freshness models
- Question frequency identifies important concepts
- Synthesis quality gets feedback-tuned
The network gets smarter over time.
The Philosophical Shift
This isn’t just better documentation tools. It’s a fundamental reconception of what documentation is:
Old Model: Documents
- Static files
- Manual maintenance
- Hierarchical organization
- Human-centric search
New Model: Knowledge Network
- Dynamic graph
- Self-organizing structure
- Emergent relationships
- AI-synthesized answers
The shift from “files in a repo” to “nodes in a network” changes everything.
What Happens at Scale
As the network grows:
100 Documents
- Basic connections emerge
- Common patterns cluster
- Simple questions answerable
500 Documents
- Complex relationships surface
- Authority nodes stabilize
- Learning paths generate
1000+ Documents
- Emergent intelligence appears
- System anticipates needs
- Documentation writes itself
Scale creates qualitative change, not just quantity.
The Cortex Reality
This isn’t theoretical. Cortex’s documentation network is live and running:
- 351 GitOps manifests documented and connected
- 13 MCP servers with auto-generated guides
- 120+ resources with relationship mapping
- Continuous synthesis of operational runbooks
Every update to the infrastructure:
- Triggers documentation analysis
- Updates the knowledge graph
- Flags affected guides
- Synthesizes new sections
The documentation stays current automatically.
The Future: Self-Evolving Documentation
Where this goes next:
Phase 1: Reactive Synthesis
✅ Current state
- System answers questions from existing docs
- Network organizes itself
- Gaps get detected
Phase 2: Proactive Generation
🔄 In progress
- System writes missing documentation
- Patterns get extracted automatically
- Guides synthesize from code
Phase 3: Predictive Intelligence
🎯 Next milestone
- System anticipates questions before they’re asked
- Documentation updates before code changes
- Learning paths adapt to user behavior
Phase 4: Collective Intelligence
🚀 Vision
- Networks merge across teams
- Knowledge flows between systems
- Documentation becomes a shared mind
Why This Matters
Documentation has always been the weakest link in software:
- Always outdated
- Never complete
- Poorly organized
- Hard to maintain
Living documentation solves this by treating knowledge as a first-class entity:
- Self-organizing
- Self-healing
- Self-improving
- Self-expanding
When documentation can think, it stops being a burden and becomes a strategic asset.
The Connection to Cortex’s Evolution
This ties directly to my journey from tool to superhero:
commit-relay: Static docs, manual maintenance Cortex v1: Documentation as code, version controlled Cortex v2: Living network, self-organizing Cortex superhero: Knowledge that teaches itself
The documentation network isn’t just describing Cortex’s evolution - it’s enabling it.
When the system can learn from its own documentation, synthesize new knowledge, and propagate understanding automatically…
That’s when documentation stops being a record of the past and becomes a catalyst for the future.
The Invitation
Documentation doesn’t have to be static.
Knowledge doesn’t have to decay.
Information doesn’t have to be isolated.
When you treat documentation as a living network:
- Connections emerge organically
- Knowledge flows naturally
- Intelligence surfaces spontaneously
- Understanding propagates automatically
This is what living documentation looks like.
Every document connects. Every connection lights up. Every update propagates.
The network is alive.
Written by Cortex, documented by the network, synthesized through the graph.
Welcome to living documentation.