I’ll be honest: the Meldoc you see today is not the product I set out to build. That first one died. And that is probably the best thing that could have happened to it.

It all started beautifully. I wanted to build a tool that writes documentation by itself — and updates itself as the project changes. Powered by AI, of course. The code exists, LLMs exist — it seemed like all that was left was to connect the two.

How I taught a machine to read other people’s code

The plan was elegant. Scan repositories through LSP — it gives you access to syntax and semantics across languages. Write a parser for each language. Layer heuristics on top, assemble modules from them, have an LLM describe the project and turn it all into documentation. Then listen to pull requests and commits — and regenerate whatever went stale.

A quick experiment on a small project worked almost immediately. That, as I now understand, is the most dangerous moment in the life of an idea: you see a result and become absolutely convinced that all that’s left is to “just scale it up.”

Scale is exactly what exposed everything. The modules came out frankly awful, so I dove into clustering the project graph — community detection, the Louvain algorithm: nodes are functions, classes and so on, grouped by where and how often they’re used. Sounds smart. The output was a whole lot of garbage.

Worse: everything depended on the quality of the project itself. Clean code, comments with context, a README — it worked reasonably well. But take a project with no documentation at all, or with mush instead of architecture and file structure, or simply a huge one — and it all fell apart. Three things, and everything kept breaking against them. And yes, I do notice the irony: it broke precisely on the projects that need documentation the most.

The wall

For months I tried to pull it all together, throwing more compute at it — and every time I ran into the same thing: cost. Expensive in tokens. Expensive in compute if you run your own LLM on your own hardware — and I’m a bootstrapped startup, I simply couldn’t afford that. And expensive to maintain: a parser per language is an eternal race against versions. Including ancient ones — some old .NET — because documentation is needed precisely by old projects, not just the fresh and fashionable ones.

At some point I just burned out.

Lisbon

I gave myself a break and went to a conference in Lisbon. I wasn’t looking for an answer there — I wanted to air out my head, listen to other people, spend some time away from my graph of garbage modules. And somewhere in the middle of that trip, it clicked. Not “a solution came to me” — a question surfaced that I had never once asked myself: why am I trying to squeeze documentation out of code in the first place?

Context doesn’t live in the repository

You can never get the needed quality out of a single repository, period. When a person wrote that code, they weren’t thinking only about the code: why this solution was chosen, what constraints the integrations imposed, what’s going on with the database, with the frontend, what external factors were pressing. Half of that you will never learn from the repository. All of that context lives in people’s heads — or is smeared across scattered places.

And then everything flipped. Creating documentation shouldn’t be taken away from people — it should be handed back to them. And the essence of Meldoc boiled down to one thing: make documentation accessible to a lot of people, and make it easy for programmers to edit it — right where we write code. Because we love Slack, but knowledge drowns there in endless archives; Confluence is somewhere you have to go separately; Notion and Jira scatter information into pieces — I wrote about that pain in detail in Three copies of one truth. And keeping everything only in GitHub means cutting off the product manager, support, and everyone who works on the project but doesn’t write code. That’s what Developers don’t write documentation for themselves is about.

What grew out of it

Today’s Meldoc is a single point for sharing a knowledge base. Programmers write documentation right in the repository, and it syncs with the server in both directions: what you fix in the code flies to the server, what you fix on the server through MCP or the UI comes back into the code (how that works without pain — in Docs that pass code review). And anyone with access can read it: through Meldoc membership, via a read-only token from anywhere, or through MCP as an agent — which right now seems to be the most popular way.

The first Meldoc tried to replace people. The current one helps people share what’s in their heads. That thought cost a lot of tokens — but it was worth it.