I’m going to say something that will make every engineering manager uncomfortable: Stop asking your team to write documentation.
Not because documentation doesn’t matter. It matters more than ever. But because asking humans to document their work after they’ve done it is a process that has failed consistently for thirty years, and no amount of “definition of done” checklists or documentation sprints is going to fix it.
The people who know the most write the least. The docs that get written are stale within weeks. And the knowledge that matters most — the decisions, the gotchas, the “why” behind the code — rarely makes it into a document because it’s not the kind of thing you sit down and write.
The Documentation Death Spiral
I’ve watched this cycle play out on every team I’ve been part of:
Week 1: “We need to document this.” Everyone agrees. Someone creates a Confluence space.
Week 4: A few pages exist. They’re pretty good. Written by the one person who cares about docs.
Week 12: The pages are getting stale. A new service was added, but nobody updated the architecture doc. The database schema changed but the data model doc still shows the old structure.
Week 24: Engineers actively avoid the docs because they’ve been burned by outdated information. “Don’t trust the wiki” becomes team wisdom. The one person who maintained it left or burned out or just stopped caring.
Week 52: Someone suggests a documentation sprint.
I’ve seen this exact pattern at four companies. The timeline varies. The outcome doesn’t.
The Inconvenient Truth About Documentation
Here’s what nobody wants to admit: the most valuable knowledge is generated during work, not after it.
When an engineer decides to use cursor-based pagination instead of offset-based — that’s a decision being made, with context and rationale, right now, in the middle of implementation. If you wait until after the sprint to document it, the rationale is fuzzy. The alternatives considered are forgotten. The specific constraint that drove the decision (“our table will have 10M+ rows and offset pagination degrades”) is lost.
When an engineer discovers that a module has a hidden coupling to another service — that’s an insight. It happened during debugging, in the heat of the moment, with full context. Ask them to write it up in a doc later and you get “Module A depends on Module B” — technically correct but missing all the useful context about how and why and what to watch out for.
The knowledge is richest at the moment it’s created. Every hour after that, it decays.
What If Documentation Just… Happened?
I started thinking about this differently when I realized that every meaningful coding session naturally produces documentation-worthy knowledge. The engineer doesn’t sit down to document — they explain their reasoning to the AI, make decisions, discover patterns, fix bugs. The knowledge is right there in the conversation.
What if the system captured it at that moment? Not the full conversation — that’s noise. But the distilled knowledge: the decision with its rationale, the pattern with its context, the error with its root cause and fix.
Not as a wiki page someone has to maintain. As structured, typed, searchable knowledge that stays current because it’s generated from the work itself.
An engineer explains why the billing service has its own database. That’s captured as a decision with rationale, scope, and history. Six months later, when a new engineer asks, “Why is billing separated?” — the answer exists. Not in a Confluence page someone forgot to update, but as a knowledge item linked to the conversation where the decision was made.
Three engineers independently use the same retry pattern. The system captures the convention. New engineers see the established pattern from their first session — without anyone writing a style guide.
Someone discovers that a module has a subtle memory leak under specific conditions. The error pattern is captured with symptoms, root cause, and fix. Next time someone sees similar symptoms, the answer is already there.
The Compound Documentation Effect
Traditional documentation is a snapshot. Someone writes it at a point in time, and it begins decaying immediately.
Knowledge captured as a byproduct of work is a stream. Every session potentially adds to it. After six months, a team has captured hundreds of decisions, patterns, and insights — without anyone writing a single doc.
A new engineer joining the team has access to all of it from their first session. Not as a reading list of stale wiki pages, but as active context that the AI uses to inform every interaction.
This is what documentation should have been all along. Not a separate activity competing for time with shipping features. A natural side effect of the work itself.
The Hard Part
This only works if the extraction is good. Capture too much and you get noise. Capture the wrong things and you pollute the system.
The key insight I keep coming back to: the entity doing the work is the best judge of what’s worth capturing. A separate system processing transcripts doesn’t have the context. The AI that participated in the conversation — that made the decision, that explored the alternatives, that understands the constraints — knows exactly what’s worth remembering.
Documentation is dead as a deliberate activity. As a side effect of working with an intelligent system? It’s never been more alive.
from DevOps.com https://ift.tt/qCPVWbj
Comments
Post a Comment