A product manager pings a developer: quick question, what happens to an invite link after it expires? The developer sighs, opens the code, answers in two minutes. Nothing about this feels like a documentation problem. It also happens about forty times a week.
The developer never notices the docs are missing, because for them nothing is missing — the code is right there, and the code doesn’t lie. Which is the uncomfortable part: the person we expect to write the documentation has the least personal use for it. And nobody else can write it.
Who actually reads the documentation
QA does — they test behavior, not code, and depend entirely on what’s written down. The product manager designs features on top of how the system works today, or how they believe it works. Support sits with a customer on the line trying to figure out where “works as designed” ends and a bug begins. Then there’s the new developer, spending their first months assembling a picture of the system piece by piece. And lately AI agents — Claude Code, Cursor — which read context in every session and take whatever they find at face value.
That’s a lot of readers for a text its author doesn’t need.
What happens when there’s nothing to read
Everyone goes to the developers. There’s nowhere else to go.
The QA version of this is a story on its own (It’s not a bug): a tester checks behavior against a spec that’s three weeks out of date, files a bug, and the developer closes it with “it’s not a bug, we changed the validation.” Two hours of several people’s time, spent dissecting a problem that doesn’t exist.
The other readers cost less per incident, but it adds up the same way. Product asks the tech lead to clarify before designing anything. Support escalates tickets it could have closed alone, and the newcomer books senior time for questions a page could have answered. The agent is the only one that doesn’t ask — it fills the gap by itself and suggests a pattern that was ripped out half a year ago.
Multiply by weeks, and the tech lead stops being an engineer and becomes a routing layer for the same five questions. The knowledge exists in the team. There’s just no way to get at it without interrupting somebody.
The problem isn’t laziness
The standard explanation is that developers hate writing docs. Maybe. But in most teams the knowledge does get written down — it just lands where the readers will never find it. READMEs and code comments that a product manager has no reason to open. Slack threads that answered the question perfectly and then sank into the archive. A Confluence space nobody visits, because visiting it is a separate errand.
The rest stays in heads.
Keep the knowledge only in the repository and you’ve locked out everyone who doesn’t work in the repository. Move it all to a separate wiki instead, and you lose the developers — they won’t maintain a tool that sits outside their workflow. Both setups fail, just for different audiences.
The principle
Meldoc is built around one rule: write where the code is; read from anywhere.
The developer keeps documentation in the repository — plain markdown files, edited in the same PR workflow as the code, no separate tool to remember. From there it syncs out to everyone else: the team reads it in the UI, external readers through public docs and read-only access, agents through MCP (MCP in Meldoc).
The sync is plumbing. The actual point is that documentation is how the rest of the team gets at what the developers know — so it has to be cheap for developers to write and easy for everyone else to reach. Those are two different requirements. Most tools optimize for one of them and quietly give up on the other; we’re trying to hold both.