I set out to document our systems. The docs found bugs I didn't know we had.
The same close reading that produces honest documentation produces correct systems. They are the same pass.
We run a portfolio of products, and over time every one of them accumulates the same quiet rot: documentation that no longer matches the code, a README written six features ago, a database that runs in production but could not be rebuilt from the files in the repo. None of it shows up in a demo. All of it bites you at the worst possible moment.
I wanted to fix the documentation half of that, so we built ourselves a tool that generates real documentation for a codebase by reading it: the architecture, the routes, the data model, and plain-language guides for the people who use the product. We ran it across three of our own production systems. It worked. That is not the interesting part.
The interesting part is what came back alongside the docs: a list of bugs. I had not asked for a bug list. But you cannot accurately describe what code does without noticing when what it does is wrong. The one rule we built in is that every documented fact has to trace to a real line of code. That rule makes the docs trustworthy. It is also, it turns out, an audit.
What it found in our own code
I am going to be specific, because specific is the only thing worth reading, and because these are our systems, not a client's.
A booking link pointing at the wrong page
On the site that books our discovery calls, the follow-up email that nudges a prospect to book was building its link from a setting that, if it was not explicitly configured, fell back to a different booking page than the one in the actual intake flow. A real lead, clicking the nudge we sent them, could land on the wrong page. On the one system whose entire job is to capture leads. That is lost revenue, sitting quietly in a fallback value.
A database that could not rebuild itself
On that same site, five database columns the application and its background jobs depend on were created by no committed migration. The live database worked, because someone had added those columns by hand. But rebuild that database from the code in the repository, in a new environment or a disaster recovery, and the application breaks on startup. The repo was not a true source of truth, and nobody knew.
A feature that would fail on first use
On another product, a feature was calling an AI model by an identifier our infrastructure could not resolve, a leftover from an earlier platform we had migrated off of. It would have failed the instant a user touched it.
Each of these normally surfaces as an outage, a lost customer, or a failed recovery, found the expensive way, after it had already cost something. We found them on a quiet afternoon, reading our own code on purpose.
Why a documentation tool catches what a code review misses
A scored code review looks for categories of problems: is there test coverage, is the dependency tree clean, are there committed secrets. It is checklist-shaped, and it is valuable. But it does not read every line and ask "and does this actually do what it claims."
Documenting forces that question on every route, every table, every function. To write "this email sends the prospect to the booking page," you have to open the code and confirm where the link actually points. The moment you do, the bug is staring at you.
What this is not
- Not a magic bug finder. It found these because the work was grounded: real reading, real tracing to real code, with a hard rule against inventing. Point a careless AI at your codebase and it will confidently document features you do not have and miss the ones you do. The value was the discipline, not the novelty.
- Not a replacement for security review, testing, or judgment. It is one more pass, a high-yield one, that most teams never run because "writing docs" sounds like a chore instead of an audit.
- Not a clean scorecard for us either. Putting these systems under a stricter review surfaced work we still owe, including a dependency advisory we need to clear. We are doing that, and we publish the gaps because hiding them is how you lose trust.
One-sentence takeaway
The same close reading that produces honest documentation also produces correct systems, because you cannot describe what your code does without noticing when it does the wrong thing, and that is why a grounded documentation pass is one of the highest-yield audits you are not running.
Let's talk
If your docs and your code have quietly drifted apart, and you suspect there are wrong links and unrebuildable databases hiding in systems that look fine in a demo, that is a 30-minute conversation worth having. I do not need slides. I need the rough shape of your portfolio and what keeps you up about it. I will tell you honestly whether this is the right thing to do and whether we are the right ones to do it.