DEV Community: Eduard Golovachuk

Your API Docs Are Lying. It's Not Your Writer's Fault

Eduard Golovachuk — Tue, 21 Jul 2026 10:00:55 +0000

Every API reference that's written by hand is out of date. Not "at risk of becoming out of date." Out of date, right now, in at least one place. I've owned developer documentation at one of the largest banks in Europe, and I did the thing every docs consultant will tell you to do: I stopped writing the reference by hand and generated it from the OpenAPI specification instead. Pipeline regenerates on release. If the spec changes, the docs change. Problem solved.

It wasn't solved. Drift came back within weeks — through a door I hadn't guarded, because I'd been treating the wrong thing as the source of truth.

The spec isn't the API. The spec is what someone typed about the API

Here's what actually happened. At our scale, the OpenAPI spec wasn't something backend engineers wrote as they coded — it was a governed contract: architects and API analysts designed it, reviewed it, froze it, and only then did backend teams build against it. That's not bureaucracy for its own sake. External partners integrate against a bank's payment API; you can't let its published contract drift on an individual engineer's whim, so the design-first process exists specifically to keep it stable and intentional.

Which is exactly what made the drift so persistent. When a team needed a new field or a widened response, going back through spec design and review was slower than shipping the feature — so they shipped against the real, running API and left the canonical spec untouched. The docs pipeline was doing its job perfectly: it faithfully generated a fresh, correct-looking reference from the one artifact everyone had agreed was the source of truth. The spec just wasn't describing the API anymore.

The obvious counter-question — I asked it myself — is: why not skip the governed-spec ceremony and just auto-export the spec from the code? Plenty of frameworks do this natively, from annotations. It sounds like it removes the problem by definition: a spec generated from code can't disagree with the code.

It removes the docs problem and reintroduces a worse one. A spec exported straight from whatever the code currently does isn't a contract — it's a live transcript of ungoverned change. Every ad hoc field a backend engineer adds under deadline pressure becomes, automatically and without review, part of the "official" API — shipped straight to partners integrated against last month's version, with nobody having asked whether the change was backward-compatible, well-named, or intentional at all. You've automated honesty. You haven't automated design. The lie doesn't disappear; it just moves from "the docs disagree with the code" to "the docs honestly describe an API nobody actually approved."

That's the real fork, and it has no automated way out: spec-first without enforcement drifts from the code; code-first without review drifts from good API design. Either direction, picked alone, just relocates where the lying happens.

This is not a documentation problem

That's the part that took me longer to admit than I'd like: neither direction of automation — docs-from-spec or spec-from-code — fixes this alone, because the actual failure sits upstream of both. My instinct, as the docs owner, was to fix it with docs tooling: better annotations, spec linting, a bot that nags people to update the YAML. All of that helps at the margin. None of it addresses the actual cause, which is a development process problem: the spec was being treated as an input to documentation, when it needed to be treated as a contract that gets updated — and reviewed — as part of building the feature, before ship, not after.

Those are two different mental models, and the gap between them is where every drifted API in the industry lives. "Update the docs" is a chore assigned to whoever remembers. "Update the contract" is part of what shipping the feature means — the same way updating the database schema is part of shipping a feature that needs a new column, not a follow-up ticket.

The fix that actually held

What eventually closed the gap wasn't a better pipeline. It was making the spec update part of the definition of done, enforced the same way code quality is enforced: a merge request that changes API behavior without a corresponding spec change doesn't pass review. Not "please update the docs" as a comment — a gate, next to the tests and the lint, owned by engineering the same way engineering owns everything else it can't ship broken.

Getting there wasn't smooth. The resistance came from an unexpected direction — not product managers, but engineering leads themselves, who read a mandatory spec review as someone else encroaching on decisions they considered theirs to make. What actually made the model stick was that the CTO backed it: once spec review had visible executive weight behind it, "I'll get to it" stopped being an acceptable answer.

Why this is worth saying to developers, not just to docs people

The uncomfortable generalization: documentation quality and product quality are not two separate outcomes of two separate disciplines. They're both downstream of the same thing — whether your team treats its interfaces as contracts or as descriptions written after the fact. A team that updates the spec as part of shipping the feature ships a more predictable API, because the discipline that keeps the docs honest is the same discipline that keeps the API from growing undocumented, inconsistent edge cases in the first place. A team that treats the spec as paperwork will eventually ship an API that not even its own engineers can describe accurately — with or without me.

Process unification isn't a documentation initiative wearing a process costume. It's the actual lever. The docs are just the first place you can see whether you're pulling it.

I build the systems that make this hold — automated generation as the visible layer, contract-first review gates as the part nobody sees. Both matter; the second one is the part most companies skip. If your "automated" docs still drift, that's usually where. DM me or find me on LinkedIn.

Your Next Developer Will Never Read Your Docs

Eduard Golovachuk — Tue, 14 Jul 2026 11:26:56 +0000

Here's a quiet shift that most companies with an API haven't priced in yet: the developer evaluating your product this quarter may never open your documentation. Their coding agent will.

Watch how integration actually happens in 2026. A developer doesn't read your quickstart, copy the curl example, and adapt it. They tell Cursor or Claude or Copilot: "integrate [your product] for payments." The agent reads the docs — or its stale memory of them — writes the code, runs it, and reports back. The human sees the result, not the journey. Your documentation just became an API consumed by machines, and it has all the problems of an API that was never designed as one.

This changes four things, and none of them are obvious.

1. Docs failure is now invisible

The old failure mode was at least loud. A developer hit a broken example, got frustrated, filed a ticket or complained in your community. Painful, but visible — you could count the tickets.

An agent doesn't get frustrated. When your docs are wrong or ambiguous, it does something worse than complaining: it confidently fills the gap from its training data — how APIs like yours usually work — and produces code that almost works. The human downstream doesn't conclude "the docs are wrong." They conclude "this API is flaky," and evaluate your competitor. You lose the deal and never see a signal. Documentation drift used to cost you a support ticket; now it costs you silently, at machine speed.

2. Your docs metrics started lying

If your docs pageviews are drifting down while API signups hold steady, that's not "docs matter less." That may be your traffic moving into channels you can't see: agents fetching pages programmatically, developers asking ChatGPT instead of opening your site, answers served from a model's memory of your docs as they were at training time. Pageviews measured humans. Humans are no longer the whole audience — increasingly not even the first audience. Measuring docs health by traffic in 2026 is like measuring API health by how pretty the dashboard is.

3. You can't fix the model. You can fix the corpus.

Try asking a popular assistant about your own product's API. There's a decent chance it answers from training data that's a year old — deprecated endpoints, renamed parameters, limits you've since changed. Companies discover this and their first instinct is to treat it as a PR problem or a "wait for the next model" problem.

It's a documentation problem. Modern assistants fetch and prefer live, well-structured sources — when there's a canonical, machine-readable corpus to fetch. When there isn't (docs walled behind JavaScript, fragmented across a wiki, no stable URLs, reference hand-written and drifting), the model's stale memory wins by default. You will never retrain someone else's model. You can absolutely make your docs the source it reaches for.

4. "Readable" now has a second meaning

What makes docs consumable for an agent is boringly concrete, and most of it is the same hygiene that was always right — just with the excuses removed:

One canonical source. Agents can't resolve contradictions between your wiki, your PDF, and your portal. Neither could humans, but humans at least asked. Agents pick one — silently.
A reference generated from the spec, not written by hand, so the machine-facing contract and the machine-facing docs cannot drift apart.
Clean, stable, fetchable pages: real URLs, server-rendered text, structured markup. If your content only exists after five seconds of client-side rendering, for an agent it barely exists. Emerging conventions like llms.txt help; the fundamentals help more.
Examples that run as written. A human adapts a broken example; an agent executes it, fails, and improvises. Copy-runnable examples were always good practice. Now they're a firewall against confident machine improvisation.

None of this is exotic. That's the uncomfortable part: the AI era didn't add new documentation requirements so much as it removed the tolerance for ignoring the old ones. Every sin your docs could get away with — because a patient human would figure it out — is now executed literally, at scale, by something that never asks for help.

The companies that get this early won't just have better docs. They'll be the ones whose products AI assistants recommend and integrate correctly by default — while competitors wonder why their "flaky API" keeps losing evaluations it never knew were happening.

Checking whether your docs work for machine readers is literally part of my documentation audit — an AI-readiness check alongside the human one. I build docs systems for API-first companies: docs-as-code, references generated from OpenAPI, LLM review on every change. DM me or find me on LinkedIn.

I Put an LLM Reviewer on Every Docs Merge Request. Here's What It Actually Catches

Eduard Golovachuk — Wed, 08 Jul 2026 13:37:40 +0000

Here's an uncomfortable truth about documentation in most engineering orgs: code gets reviewed, docs don't. A pull request with code changes gets two approvals and a CI run. A pull request with docs changes gets a "LGTM" from someone who scrolled through it in eight seconds — if it gets reviewed at all.

I was the sole owner of documentation for a set of AI platforms at a large tech company in Eastern Europe. Sole owner means exactly what it sounds like: there was no second pair of eyes. Every broken code example, every outdated parameter, every style inconsistency was going to ship unless I caught it myself. At 30–40 docs merge requests a week — spiking toward 50 in release weeks — from a hundred engineers across three departments, review alone was eating half my day. I was the bottleneck and the single point of failure at the same time.

So I did what any engineer would do with a bottleneck: I automated it. I built an LLM reviewer into the docs pipeline. Every merge request now gets an automatic review before a human ever looks at it.

What it actually catches

Not what I expected, honestly. I assumed the main value would be style — and it does enforce style. But the real catches, ranked by how much pain they prevent:

Broken and outdated examples. The classic failure mode of platform docs: the API changed three releases ago, the example didn't. The reviewer cross-checks examples against the current system state and flags mismatches. This alone would justify the whole setup — a broken quickstart example is the single fastest way to lose a developer.

Contradictions between pages. Page A says the limit is 100 requests per minute, page B says 60. No human reviewer catches this, because no human reviewer holds the whole corpus in their head. The LLM does.

Silent scope creep. A writer (or a developer editing docs) quietly documents behavior that doesn't exist yet, or removes a warning that still applies. The reviewer flags claims that changed without a corresponding release reference.

Style violations — last on the list, and that's the point. Style is what people think docs review is about. It's the least valuable part.

And the meta-effect that mattered most: merge requests stopped queuing on me. Before, every docs change sat in the bottleneck of a single human reviewer — my calendar was the pipeline's latency. Now the machine does the first pass in minutes, authors fix the mechanical findings themselves, and what reaches me is already clean. Time-in-review dropped from a 2–3 day queue to same-day, and I stopped being the reason a finished doc wasn't live.

What it doesn't do

It doesn't write the docs. It doesn't know what the reader needs, what to explain and what to leave out, how the information should be structured. It reviews — against the spec, against the corpus, against the style guide. The judgment stays human.

My favorite false positive makes the point better than any argument. We were documenting a custom no-code builder for feature extractors — a genuinely bespoke piece of our platform, built in-house, existing nowhere else. The LLM reviewer flagged our description as "inaccurate" and helpfully suggested a correction… describing how feature extraction works in the generic ML tooling it had seen in its training data. The feature was too new and too ours to exist in the model's world — so the model concluded the docs were wrong, not that the world had something it hadn't seen. It reviewed our product against its memory of other products, with total confidence.

That's the boundary in one anecdote: an LLM reviewer is superb at checking your docs against things that are written down — the spec, the corpus, the style guide. For anything genuinely novel, the human who built it is the only source of truth, and the AI-reviewer's confident "correction" is exactly the hallucination you built the pipeline to catch. Which is why the reviewer proposes and a human disposes — never the other way around.

The part nobody tells you

The hard part wasn't the LLM. The hard part was that an LLM reviewer is only useful if your docs live in a pipeline at all: docs-as-code, version control, CI, a reference generated from a spec instead of written by hand. If your documentation is a pile of pages in a wiki, there is nothing to hook a reviewer into. The AI is the last 10%. The system is the other 90%.

Which is, in my experience, the actual state of documentation at most companies: not "we need AI," but "we need the system that AI could then plug into."

I build these systems for API-first companies — docs-as-code pipelines, references generated from OpenAPI, LLM review on every change. If your docs are a pile of pages in a wiki and your integrations are slower than they should be, that's exactly what my documentation audit finds and fixes. DM me or find me on LinkedIn.