Blog

You've inherited a project eight years older than any of the current developers, and "document the system" has been in the backlog for a year. Well: you don't need to describe everything. You need to close holes one at a time, starting with the ones someone has already referenced — that's free, honest prioritization. A ritual for every day — in this article. Really, the whole series was leading here.

The later you find a problem, the more it costs — in production it's hotfixes, in code it's rewrites, on paper it's zero lines. A live example from our duplicate detector: how many options died before the first commit — a separate audit tool, contradiction detection, LLM "semantic fingerprints." All killed for free, on paper. A follow-up to the post about our process.

Every tech lead has this task. It's been in the backlog for half a year under the name "sort out the documentation," and nobody picks it up. Not out of laziness — the task has no boundaries, and a task without an end never gets done. We turned it into a finite list with a clear "done" — one call, and an honest note about what this audit can't do.

"The product manager got this all wrong!" — a real line from a real refinement, minute forty. For years product managers brought "finished" designs and developers tore them apart — and there are no villains in this story. I spent weeks turning over the question "where do we fix this" until it clicked: we were demanding the wrong competence from people.

A team I know kept their docs in three places: a wiki for insiders, markdown for developers, a website for external users. At any given moment nobody could say which copy was still current. The three audiences are real — they do read docs differently. The three copies of the text were never the necessary part, and that's the part we removed.

Fix the code — commit and PR. Fix the docs — different tool, different tab, different mood. Guess which half of the work is always "later." We removed that fork: docs are plain markdown files in your repository — same git, same review. An honest look at what that gives you and what it doesn't.

Friday evening. QA reads the comment on the ticket they filed that morning: "It's not a bug, we changed the validation three weeks ago." Half a day of work down the drain — and nobody's at fault: QA tested exactly what the docs said. The docs just lied. The anatomy of a false bug, from commit to closure — and how to remove "don't forget to update" from the equation.

Two people, two projects, two pages about the same thing. Nobody's at fault — that's how any knowledge base grows once more than one person writes in it. The problem is that one copy gets fixed and the other gets forgotten, while the reader is sure they've read the documentation. How we made duplicates visible without a "Saturday deep-clean" — in this article.

Claude Code suggests a pattern you ripped out half a year ago, and sounds completely sure about it. The agent isn't stupid — it just has nothing to read beyond your code and its training data. It can't walk over to a colleague and ask why things are the way they are, so it guesses. What actually helped us: giving it something to read.

A product manager pings a developer with a question the docs should have answered. The developer never noticed the docs were missing — they can read the code. QA, support, new hires and AI agents can't. When there's nothing written for them, every one of their questions lands on the same few people, and the tech lead slowly turns into a help desk.

My routine now is to open Claude and think out loud while it walks our knowledge base on its own. No RAG pipeline, no snapshots going stale: the agent pulls not a document but exactly the chunk it needs, and edits just as precisely. The best proof — this very series is assembled by a team of AI agents through the same MCP. Here's the kitchen from the inside.

Two people on your team are describing the same entity in different projects right now — and have no idea about each other. There's no link between their documents, but semantically it's one piece of knowledge. We built a graph that finds such connections on its own, without a single manually placed link.

The first Meldoc died. I honestly tried to teach a machine to generate documentation from code — LSP, per-language parsers, graph clustering — and hit a wall of cost and garbage modules. Then, somewhere in Lisbon, a question clicked that I had never once asked myself. That question started the product you see today. Here's the whole story of the failure, unvarnished.