Building Domain Memory to preserve your system’s why @ DDD Europe

Most systems don't turn into "legacy" because of bad code. They turn into legacy when the people who carry the system's mental model leave. Peter Naur called it the "theory of the system": the why, the trade‑offs, the language, and the shape of the solution.

Intuitively, we know this. Yet as an industry, we keep trying to solve legacy with more tech and explicit knowledge tracking: better docs, code comments, wikis, diagrams, automated tests and AI coding assistants. We don't tackle the actual problem: tacit knowledge loss.

What you will learn from this talk:
- Understand why this cannot be solved by better docs and tech alone.
- How only human collaboration through practices like modeling, pairing and living language can keep theory alive.
- How to measure and improve knowledge continuity in your team with simple metrics.

If we want to create software that lasts, we need to encourage human collaboration across disciplines, backgrounds and personalities (including our new AI buddies). Learn how to use your human power skills to better understand the problems you're facing and build systems that last!

Transcript

1. Nico Krijnen Building Domain Memory to preserve your system's why
3. Legacy Systems Rule the World
4. When is code "Legacy"? • Missing tests • Code you got from somebody else • Code that you're scared of • Makes the business loads of money
5. How does code become "Legacy"? Knowledge "left the company"
7. Causes of Developer Turnover Sources: Stack Overflow Developer Survey 2022 – 23; Atlassian Developer Experience Report 2024; Storyblok Dev Survey 2023; Dice Tech Career Survey 2023; Work Institute Retention Report 2022; Gallup State of the Global Workplace 2023; DDI Retention Report 2019.
8. Causes of Developer Turnover Sources: Stack Overflow Developer Survey 2022 – 23; Atlassian Developer Experience Report 2024; Storyblok Dev Survey 2023; Dice Tech Career Survey 2023; Work Institute Retention Report 2022; Gallup State of the Global Workplace 2023; DDI Retention Report 2019.
9. Causes of Developer Turnover Sources: Stack Overflow Developer Survey 2022 – 23; Atlassian Developer Experience Report 2024; Storyblok Dev Survey 2023; Dice Tech Career Survey 2023; Work Institute Retention Report 2022; Gallup State of the Global Workplace 2023; DDI Retention Report 2019.
10. Causes of Developer Turnover Sources: Stack Overflow Developer Survey 2022 – 23; Atlassian Developer Experience Report 2024; Storyblok Dev Survey 2023; Dice Tech Career Survey 2023; Work Institute Retention Report 2022; Gallup State of the Global Workplace 2023; DDI Retention Report 2019.
11. Causes of Developer Turnover Sources: Stack Overflow Developer Survey 2022 – 23; Atlassian Developer Experience Report 2024; Storyblok Dev Survey 2023; Dice Tech Career Survey 2023; Work Institute Retention Report 2022; Gallup State of the Global Workplace 2023; DDI Retention Report 2019. 😬
13. ...
14. Nico Krijnen
18. Jack Jansen and Jennifer Steiner in prefab offices Lambert Meer
19. able office Paul Vitanyi in vertically mobile office
22. ABC
23. ABC
24. ABC
25. ABC AI
26. Building Domain Memory to preserve your system's why
27. What is code?
28. Code = map 🌍 to 🖥
29. Code = map 🌍 to 🖥 Result: programs / software
30. Value of software
31. Value of software Flexible
32. Value of software 🌍 changes = 🖥 changes Flexible
33. Software has eaten the world
34. What is programming? "Activity of forming theory of matters at hand" – Peter Naur, Programming as Theory Building, 1985
35. What is programming? Program ! = Fully captured by it's source code
36. What is programming? Program ! = True essence = Theory constructed by programmers The mental model of how it works, why it was designed that way and how it fits in its intended domain.
37. Contrast with Formalist approaches Dominant view in 1970s–80s on programming theory: • Programs are mathematical objects. 𝑓 • Correctness comes from formal specifications and proofs. 📃 • The programmer’s role is to implement specifications faithfully, ideally in a way that can be mathematically verified. 👍 LGTM • Human understanding is secondary to formal reasoning. 🧐
38. The Result Production View Input = Requirements & Observing real world Programmers = Replaceable "machines" Output = Code & Docs
39. Naur’s view (“Programming as Theory Building”) • Programs are human constructions. • The essence of programming lies in the mental theory programmers hold, not just in formal documents. • Specifications and proofs may help, but they are incomplete unless tied to programmer understanding. • Human understanding is central — code and documents are secondary artifacts.
40. Programming as Theory Building Theory-Building View Input = Observing real world, situational experience Programmers = Build a mental theory Output = Theory: mapping between real world & code Code = Side-product
51. Solution: Put the "Theory" into written documentation
52. Except: you can't... Solution: Put the "Theory" into written documentation
53. Typical knowledge management doesn't build theory Practice Why teams reach for it Big documentation drives Feels scalable. Leadership can ask for it, track it, report progress. Wikis / knowledge bases Promise single searchable place for “what team knows.” Walkthrough videos Easy async onboarding. Low coordination cost once recorded. Runbooks for everything Give sense of operational safety, repeatability, control. AI / RAG as knowledge base Fast answers, low friction, always available.
54. Tacit Knowledge Explicit Knowledge Definition Personal, experiential know-how that’s hard to articulate. Formal, documented knowledge that can be written down, codified, or stored. How it’s gained Through practice, intuition, trial-and- error, observation. Through reading, lectures, databases, manuals. How it’s shared Mentoring, storytelling, shadowing, demonstration, practice. Books, reports, procedures, checklists, training materials. Examples Riding a bike, a chef’s “feel” for seasoning, a leader’s intuition in a crisis. Recipes, standard operating procedures ( SOPs), user manuals, financial reports. Transfer difficulty Hard to capture in words; usually requires personal interaction. Relatively easy—just copy, store, or transmit the written or digital record. Value Enables creativity, innovation, and expert judgment. Provides structure, consistency, and scalability.
55. Tacit Knowledge Explicit Knowledge Definition Personal, experiential know-how that’s hard to articulate. Formal, documented knowledge that can be written down, codified, or stored. How it’s gained Through practice, intuition, trial-and- error, observation. Through reading, lectures, databases, manuals. How it’s shared Mentoring, storytelling, shadowing, demonstration, practice. Books, reports, procedures, checklists, training materials. Examples Riding a bike, a chef’s “feel” for seasoning, a leader’s intuition in a crisis. Recipes, standard operating procedures ( SOPs), user manuals, financial reports. Transfer difficulty Hard to capture in words; usually requires personal interaction. Relatively easy—just copy, store, or transmit the written or digital record. Value Enables creativity, innovation, and expert judgment. Provides structure, consistency, and scalability. Code Docs Tests Theory
56. Tacit Knowledge Explicit Knowledge Definition Personal, experiential know-how that’s hard to articulate. Formal, documented knowledge that can be written down, codified, or stored. How it’s gained Through practice, intuition, trial-and- error, observation. Through reading, lectures, databases, manuals. How it’s shared Mentoring, storytelling, shadowing, demonstration, practice. Books, reports, procedures, checklists, training materials. Examples Riding a bike, a chef’s “feel” for seasoning, a leader’s intuition in a crisis. Recipes, standard operating procedures ( SOPs), user manuals, financial reports. Transfer difficulty Hard to capture in words; usually requires personal interaction. Relatively easy—just copy, store, or transmit the written or digital record. Value Enables creativity, innovation, and expert judgment. Provides structure, consistency, and scalability. Theory Code "the art" of doing something Docs Tests "the instructions" for doing something
57. "the art" of doing something Is not something you can write down!
59. Mental Theory is crucial Yet our industry seems oblivious to that
60. The cost of generating code is approaching zero
61. Writing code was never the actual product. Cost dropping to zero Typing syntax Understanding what change to make
63. Brooks's Law "Adding manpower to a late software project makes it later." - Fred Brooks, 1975, The Mythical Man-Month
64. Brooks's Law of AI "Adding more AI to a late software project makes it later." - Some Guy, 2026 @ DDD EU AI does not add more people. It adds more change. The effect is the same.
65. We can fix this!
69. The diagram isn't the value. The conversation is.
70. Not so easy anymore
71. "Having only one computer around had some good social effects: there was also a single terminal room, where everyone went who did anything with computers. As a result you got to know every computer user well, and there were lots of discussions and exchange of information." – Steven Pemberton The effect of physical organization
72. The effect of physical organization
73. Damn! So we're doomed!?
74. Bummer! But AI can fix this!
75. AI assisted Good AI-assisted workflow produces: • design rationale • architectural alternatives • tradeoff discussions • assumptions Historically much of that stayed in someone's head. AI can make fragments of theory more observable. Theory building
76. AI as co-worker on the team • A team-mate that never leaves • That retains theory
77. AI as co-worker on the team What AI is good at ✅ • explicit representations of knowledge • digesting, indexing, and summarizing artifacts: code, docs, tickets, PRs • generate intellectual scaffolding: structured documentation, cross- references, diagrams. What AI struggles with 🫤 • Tacit, embodied competence • “I know this hack works because last time we hit a race condition under load,” or • “this module is fragile, so don’t touch X without checking Y.” These judgments live in lived practice, not just artifacts.
78. The human parallel
79. The human parallel Think of a junior developer: • They read docs (sometimes). • But they really learn by pairing, making mistakes, fixing bugs, asking questions, living through incidents. • Over time, they develop a feel for the system: a lived theory.
80. The human parallel For AI to match that, it needs a developmental trajectory: Experience → feedback → adaptation → social learning → intuition-like heuristics. 🤖
81. The human parallel Today’s LLMs don’t really “try” things and live with the consequences. They predict text. 🤖
82. The human parallel Future AI would need: • safe sandboxes where it can make mistakes, • see consequences, • and refine its approach. This echoes reinforcement learning & AI agents but at the scale of real systems and over long horizons. 🤖 ✨
83. 🛠🤖
84. 🛠🤖 😴
85. 🛠🤖 😴
86. Damn! So we're really doomed!?
87. Actually, we can fix it!
88. Goal? Preserve theory
89. Goal: Create conditions that let theory continually evolve Apply systems-thinking
90. Ok, sounds good. How?
91. Find Leverage Points Places in a complex system where a small, strategic shift can produce massive, cascading changes throughout the entire structure. Theory Building Techniques
92. Experience acceleration Exit Harvesting Sessions SHINES WHEN Someone announces departure with 2 + weeks notice. Critical for single-owner systems. HOW IT WORKS Joint modeling sessions where the departing dev narrates their mental model while another drives. Not an interview — a shared experience on the code they hold alone. RISKS Too late if notice is short. Turns into a doc dump if not structured as joint problem-solving. ••◦ HYBRID
93. Experience acceleration Reverse Shadowing SHINES WHEN When you can't articulate what you know — watching someone struggle reveals it. HOW IT WORKS Expert watches less-experienced dev attempt change in their area, intervenes only when asked. Observes what's non-obvious about their own theory. RISKS Uncomfortable for both. Requires trust and explicit agreement that struggle is the point. ••◦ HYBRID
94. Experience distribution Cross-Team Theory Exchanges SHINES WHEN Microservice architectures with implicit coupling. Platform/ product team boundaries. HOW IT WORKS Teams sharing a dependency present their domain model and the "why nots" quarterly. Not API demos — reasoning sessions. RISKS Easy to turn into show-and-tell. Must include what was rejected and why. ••• REMOTE
95. Experience distribution Calendar-blocked pairing SHINES WHEN Remote teams where organic knowledge spread doesn't happen. Makes the implicit explicit. HOW IT WORKS Formalize: every quarter, person A spends 2 full days pairing in person B's area, and vice versa. Calendar-blocked, non- negotiable. RISKS Feels bureaucratic. Must be actual work, not tours. The pair must ship something together. ••• REMOTE
96. Experience preservation Living Decision Logs in Code SHINES WHEN Teams with clear context boundaries. Prevents 'why is this here?' archaeology. HOW IT WORKS DECISIONS.md inside the bounded context: "why is the boundary here?" and "what did we reject?" Reviewed in PRs. RISKS Still explicit knowledge — only works as a prompt that triggers the reader to ask questions. Not a replacement for experience. ••• REMOTE
97. Experience preservation Knowledge Heat Maps SHINES WHEN Portfolio-level decisions, capacity planning, risk conversations with leadership. HOW IT WORKS Visualize per bounded context: who can explain, who can change alone. Color-code by bus factor. Make risk visible in planning. RISKS Subjective. Can create perverse incentives (hoarding to appear indispensable). ••• REMOTE Blog
98. Experience preservation Theory Debt Standups SHINES WHEN Any team. Extremely low ceremony. Social pressure to distribute hoarded knowledge. HOW IT WORKS Weekly 10-min question: "What do you know that nobody else on this team knows?" Make single-points-of-failure visible. Follow up with pairing. RISKS People underestimate what they uniquely know. Combine with pairing or it degrades into reporting. ••• REMOTE Blog
99. Experience preservation Thoughtful git commits <issue|type>: <title|summary|what> <description|why> # Description should answer: # Why are the changes necessary? # How do changes address the issue? # Why have I made these changes? # What side effects do the changes have? # What are the changes in reference to? “When a programmer first creates his code, only he and God know how it works, a few months down the line and only God knows.”
100. Ok, nice and practical. But does that change the system?
101. You get what you measure! Do measure: • Hours mob or paired • Bus factor • Psychological Safety Do not measure: • Knowledge contributions per Employee (docs, wiki, posts) = explicit knowledge, not tacit!
102. % of coding hours spent in pair or mob programming Protect against single points of failure & ensure tacit knowledge spreads beyond “the expert.” Tacit knowledge is shared most effectively when engineers see each other think in real time. % of critical systems where >1 engineers can handle incidents, releases, or major changes Monthly or quarterly survey with 2–3 focused questions Safe, learning-oriented culture forms foundation for tacit knowledge flow.
103. Building Domain Memory to preserve your system's why
104. Value of software Flexible 🌍 changes = 🖥 must adapt Value != The code requires strong Mental Theory
109. Nico Krijnen Building Domain Memory to preserve your system's why Theory Building Techniques