Dual-Engine Knowledge System
If you’ve ever struggled to keep documentation both current and comprehensible, you’re not alone. Most knowledge systems force a false choice: either write narrative documentation that tells the story of how things evolved, or create reference documentation that describes the current state. But the best systems do both.
Over years of building documentation systems — for engineering teams, for this blog, for personal knowledge management — I’ve noticed a recurring pattern. The systems that work best aren’t single-engine; they’re dual-engine. They maintain two complementary views of the same information: the delta (what changed and why) and the current state (what is now).
The Git Analogy
Think about how Git works. At its core, Git stores a series of snapshots — commits that represent the state of your code at specific moments in time. Each commit includes a message explaining what changed and why. This is the delta view: a narrative of evolution.
But when you check out a branch, you don’t see the history. You see the working tree — the current state of every file. This is the reference view: a complete picture of what exists right now.
Both views are essential. The commit history tells you why the code looks the way it does. The working tree tells you what the code actually is. Without the history, you lose context for decisions. Without the working tree, you can’t actually use the code.
This same pattern appears everywhere in information systems, once you know to look for it.
The Framework
A dual-engine knowledge system maintains two synchronized views:
The Delta Engine captures change over time. It’s narrative, chronological, and decision-focused. It answers: What changed? Why did we change it? What were the alternatives?
The Current State Engine captures the present moment. It’s reference-oriented, comprehensive, and descriptive. It answers: What is true right now? How does it work? What are the facts?
The key insight: the delta engine should be the source of truth. You write changes as they happen — the decision, the rationale, the context. The current state is then synthesized from the accumulated deltas, either manually or automatically.
This isn’t just a documentation pattern. It appears in software architecture (event sourcing with materialized views), version control (commits with working trees), system documentation (ADR with architectural reference) and even legal systems (case law with codified statutes).
Applications
Here’s where this framework gets practical:
Personal Knowledge Management
Tools like Obsidian excel at this. Your daily notes capture the delta — what you learned, what you thought, what connections you made. Your evergreen notes capture the current state — distilled principles, permanent reference material. The daily notes feed into and update the evergreen notes over time.
If you’ve read The Great Obsidian Mystery series, you’ll recognize this pattern in the DATA Framework. The four folders map naturally onto the dual-engine model: Delivery (active projects and their outcomes) and Assets (people, concepts, reference materials) form the current state engine — they describe what you’re working on and what you know right now. Timeline (daily notes, meeting records, periodic reviews) is the delta engine — it captures what happened, when, and in what sequence. The fourth folder, Arsenal, sits outside the model as pure infrastructure (templates, images, configurations that make the system run).
Team Documentation
Engineering teams often struggle with architecture decision records (ADRs). The ADRs capture decisions as they happen — the delta. But teams also need architecture diagrams and API documentation — the current state. The best teams treat ADRs as the source of truth and update reference docs as decisions accumulate.
Data Warehousing
Data engineers encounter this tension in a very literal way with Slowly Changing Dimensions (SCD). A classic dimension table — say, a customer table — is a pure current state engine: it tells you what’s true right now. But when business requirements demand knowing what was true at a given point in time, you need to retrofit a delta view into that evergreen design. SCD Type 2, for instance, adds versioned rows with valid_from and valid_to dates — essentially layering a chronological narrative on top of a reference table. The fact that entire SCD taxonomies exist (Types 1 through 6) is evidence of how fundamental this tension is: current state alone is never enough once the system reaches a certain complexity.
Documentation Taxonomies
The Diátaxis framework offers a more fine-grained classification of documentation into four types: tutorials, how-to guides, reference, and explanation. These map cleanly onto the dual-engine model. Tutorials and how-to guides are action-oriented and sequential — they walk you through a process step by step, capturing the doing. They belong to the delta engine. Reference and explanation describe what something is — factual, stable, descriptive. They belong to the current state engine. Diátaxis doesn’t frame it this way, but the underlying tension it addresses — why mixing tutorials with reference material feels wrong — is precisely because they serve different engines.
Content Strategy
This blog uses a dual-engine structure. Posts tell stories — they capture ideas as they emerge, explore thoughts in progress, document migrations and discoveries. They’re the delta engine: narrative, timely, exploratory.
The concepts pages serve a different purpose. They’re reference material — evergreen, updated, comprehensive. Each concept includes status indicators (Bail, Watch, Bet, Default) showing my current confidence in the technology. They’re the current state engine: factual, maintained, definitive.
The radar visualization on concept pages lets you see at a glance where each technology stands in my evaluation. A tool marked “Bet” has proven its value. One marked “Watch” is promising but unproven. This is the current state synthesized from many delta experiences captured in posts.
When I write about Astro or Cloudflare in a post — say, the Astro migration or the Cloudflare migration — I’m capturing a moment in time: the migration experience, specific challenges, particular insights. The concept page then synthesizes these moments into a stable reference: what the tool is, when to use it, where it stands in my evaluation.
Trade-offs
This approach isn’t free. The main cost is maintenance overhead — keeping two views synchronized requires discipline.
But here’s the mitigation: by choosing the delta as your source of truth, you reduce the maintenance burden. You write the narrative as it happens (easy, natural, part of your workflow). Then you periodically update the current state view (scheduled, intentional, synthetic). The delta drives the current state, not the other way around.
Another challenge: cognitive load. Users need to understand which view to use when. The solution is clear navigation and consistent conventions. Posts are stories. Concepts are references. The URL structure and visual design make this distinction obvious.
Don’t use this pattern for simple systems. If your documentation needs are straightforward, a single-engine approach is simpler and faster. Reserve dual-engine systems for contexts where the history matters as much as the present.
Getting Started
If you want to implement a dual-engine system, start with the delta.
Don’t try to build both engines simultaneously. Begin capturing changes as they happen — decisions, discoveries, migrations. Write these as narrative documents, chronological logs, or decision records. This is the natural way humans document: we tell stories about what happened.
Once you have a critical mass of deltas, you’ll start to see patterns. Certain concepts emerge repeatedly. These become your current state pages — synthesized from the accumulated deltas. Update them periodically as new deltas arrive.
Final Thoughts
The dual-engine pattern isn’t new. Git has used it for decades. Event sourcing systems rely on it. Legal systems evolved it over centuries. What’s new is recognizing it as a general framework for knowledge management.
Most documentation failures stem from forcing everything into a single format. Either everything becomes narrative (hard to reference) or everything becomes reference (loses context). The dual-engine approach accepts that different information serves different purposes at different times. In a way, it’s a strategy against entropy — the natural tendency of information systems to decay into disorder. The delta engine captures signal before it dissipates; the current state engine distills it into something usable before complexity overwhelms.
Your system needs both memory and presence. The delta provides memory — the story of how you got here. The current state provides presence — the clarity of where you are. Together, they give you something neither can provide alone: understanding.
Start with the delta. Let the current state emerge. Maintain the relationship. That’s the dual-engine knowledge system.
Want to see it in action? Explore how this blog structures concepts as current state references while posts serve as the delta narrative. Or check out The Great Obsidian Mystery series, where the DATA Framework puts this dual-engine pattern into practice for personal knowledge management.
Have you implemented something similar? I’m curious about your documentation strategies — find me on LinkedIn or GitHub.
