Too Many Words, Not Enough Sense: The Great British API Documentation Catastrophe

There is a particular kind of suffering reserved for developers who open a new API's documentation at 9am, full of optimism and biscuits, only to find themselves staring at what appears to be the extended director's cut of a legal thriller. Forty-seven endpoint descriptions. Seventeen authentication flows. A glossary that references other glossary entries. A "Quick Start" guide that runs to six thousand words.

By 9:15, they've closed the tab. By 9:20, they're on Stack Overflow. By 9:30, they've decided your API probably isn't worth the bother.

Welcome to the Great British API Documentation Catastrophe — a slow-motion disaster unfolding across server rooms and Slack channels from Bristol to Aberdeen, perpetuated by well-meaning engineers who genuinely believe that more words means more clarity.

It doesn't. It never has. And it's time someone said so on a website named after a beermat.

The Paradox of Thoroughness

Here's the thing about over-documented APIs: they come from a good place. The team writing them has lived inside this system for months, possibly years. They know about the weird rate-limiting behaviour on Tuesdays. They remember the incident in February when someone passed a null value and everything caught fire. They want to protect future developers from pain.

So they write it all down. Every caveat. Every edge case. Every historical footnote about why the user_id field is actually called legacy_customer_ref in three of the twelve endpoints.

The result is documentation that is, technically speaking, comprehensive — and practically speaking, completely unusable.

This is the paradox of thoroughness: the more you try to explain everything, the harder you make it to understand anything. Documentation written for every possible scenario serves no actual scenario particularly well. It's the software equivalent of a restaurant menu that lists every possible dietary substitution across forty pages of laminated card. Impressive. Exhausting. Nobody's reading it.

What Good Looks Like (It's Shorter Than You Think)

The best API documentation in existence shares a handful of characteristics, and none of them involve word count.

Stripe's documentation is frequently cited as the gold standard, and rightly so. You can get a card payment working in minutes. The getting-started section fits comfortably on a single screen. The reference material is there when you need it, but it doesn't ambush you on arrival. The whole thing communicates a single, quiet message: we've thought about this so you don't have to.

Twilio. SendGrid. Shopify. The pattern repeats. The APIs that developers actually enjoy using — and more importantly, actually use — are the ones that respect your time at the door.

Now contrast that with the documentation you've probably encountered from a mid-sized British enterprise software vendor. The kind that opens with a four-paragraph disclaimer. That requires you to read a separate "Concepts" section before you're permitted to look at any actual endpoints. That presents its authentication process as a flowchart with seventeen decision nodes.

There's nothing wrong with the underlying API. The problem is the documentation has been written for the person who built it, not the person who needs to use it.

The Beermat Test for Technical Docs

At Beermat Software, we're obviously partial to a beermat as a unit of measure. So here's a practical framework — the Beermat Test — for working out whether your API documentation has crossed the line from helpful into self-indulgent.

Step one: The thirty-second skim. Hand your documentation to a developer who's never seen your API. Give them thirty seconds to skim the homepage or landing section. Can they tell you, without prompting, what your API does and how to make their first call? If they can't, your opening section has failed. Rewrite it until they can.

Step two: The one-pager challenge. Write a single-page summary of your API. Not a teaser. Not a marketing page. An actual technical summary: what it does, how authentication works, what the base URL is, and three example calls covering the most common use cases. If you cannot write this in under five hundred words, you don't yet understand your own API well enough to document it.

Step three: The "why is this here" audit. Go through your existing documentation and ask, for every section, why it exists. Not whether it's accurate — accuracy is table stakes — but whether a developer actually needs it before they can do something useful. Anything that exists purely to demonstrate thoroughness rather than enable action is a candidate for the bin, or at least a collapsible "Advanced" section that no one is forced to read.

Step four: Count your caveats. Caveats are the documentation writer's comfort blanket. Every time something is slightly complicated, the instinct is to add a caveat. "Note that this behaviour may differ in certain circumstances." "Please be aware that legacy accounts use a different authentication flow." "This endpoint is deprecated but still supported for historical reasons." Each individual caveat seems reasonable. Collectively, they create a document that reads like it was written by someone who's been on the receiving end of too many support tickets and is now terrified of being blamed for anything. Ruthlessly prune them.

The Hidden Cost Nobody's Counting

Poor API documentation isn't just annoying. It has a measurable commercial cost that British tech companies are almost universally ignoring.

Every developer who bounces off your documentation and reaches for a competitor's API is a lost integration. Every hour a competent engineer spends deciphering your authentication flow is an hour not spent building something valuable. Every support ticket raised because someone couldn't find the answer in your docs is money spent answering a question you should have pre-empted.

And then there's the subtler cost: reputation. Developers talk. The British tech community, for all its sprawling geography, is remarkably small and remarkably opinionated. If your API is known as "the one with the terrible docs," that reputation travels fast and sticks hard.

The Fix Is Not a Documentation Tool

At this point, someone in your organisation will suggest adopting a new documentation platform. Confluence, Notion, GitBook, Readme.io — take your pick. These are fine tools. They are not the answer.

The answer is editorial discipline. It's deciding, as a team, that documentation is a product in its own right, deserving the same ruthless user-focus you (hopefully) apply to your actual software. It's having someone whose job it is to read your docs as a stranger would, and to cut mercilessly everything that doesn't serve that stranger's immediate needs.

It's writing less. Much less. And making every word earn its place.

The beermat, as a metaphor, does a lot of work around here. But nowhere does it apply more directly than to technical documentation. If you can't sketch the essence of how your API works on the back of something you found on a pub table, you haven't finished thinking about it yet.

Go back. Think harder. Write less. Your developers — and your support queue — will thank you.