API Documentation: Good vs. Great

Over the past year, we ran structured audits on docs for more than a dozen SaaS and API-first companies. They covered dev tools, data platforms, AI infra, and security products.

The products varied in type, age, and budget. But the gap between good and great docs showed up in the same five places almost every time.

The goal is not to call anyone out. These issues are common. They are also specific enough that any team can check its own docs in 20 minutes.

1. Reference docs are written for humans, not machines

Most API documentation still assumes a developer is reading top to bottom in a browser. That is getting more costly.

More and more, the first "reader" of docs is an AI agent or coding assistant. It tries to find an endpoint, a parameter, or an auth flow for someone else. And agents do not skim. They parse structure.

We saw the same pattern often: docs that sounded great when read aloud, with clear prose, good examples, and a sensible order, but hid machine-useful facts inside paragraphs. Parameter types, required or optional fields, error codes, and rate limits were often buried in text instead of shown in fixed blocks.

A person may forgive that. An agent trying to build a valid request usually will not.

Great API documentation separates the two jobs. It uses prose to explain why something matters. It uses fixed blocks, like tables, typed schemas, and Swagger or OpenAPI examples, to show what the system expects.

If reference pages do not follow the same shape from endpoint to endpoint, that is usually the first sign.

2. Tutorials, how-to guides, and reference pages are mixed together

This is the classic Diátaxis problem, and it is still one of the most common structure issues in documentation. A single page often tries to be a getting-started tutorial, a task-based how-to guide, and a reference page at once. That usually happens because the page was written in one pass by the person who built the feature and was never reshaped after that.

The cost is easy to see when someone uses the docs under pressure.

A developer fixing a production issue at 2 a.m. does not want a friendly onboarding story. They want the one missing fact, fast.

A new user checking the product does not want a dense reference table. They want a guided path through a working example.

When one page tries to do both jobs, it usually does neither well.

Strong docs sites have a content model, even if they do not name it. Tutorials are for learning and assume nothing. How-to guides are task-based and assume some basics. Reference is full and assumes the reader already knows what they need. Explanation covers the reasons, tradeoffs, and design choices.

The docs sites that score well usually draw those lines clearly, even if the navigation does not label them that way.

3. Voice and terms drift across the site

Docs are rarely written by one person at one time. They grow over time. A founder writes the first version, an engineer adds a page during a launch, and a new hire expands the library six months later.

Without a style guide that people actually use, terms begin to drift. The same idea gets called three different names. Code examples switch rules from page to page. The voice shifts between casual and formal based on who wrote the draft.

None of this is fatal on its own, but it adds up fast.

A developer cross-checking two pages to solve one problem now has to spend extra time asking whether "workspace" on one page and "project" on another are the same thing. That is friction at the wrong moment.

The docs that felt most impressive were not always the most polished. They were the most consistent. One voice, one set of terms, and one code style on every page made the site easier to trust.

4. Navigation follows the org chart, not the task

A surprising number of docs sites are built around how the product team thinks about the product, not how a developer shows up with a problem.

Labels like "Ingestion," "Transforms," or "Serving Layer" make sense to the team that built the system. They mean much less to someone who just wants to get data in and query it back out.

This hurts more when search is weak.

If the navigation does not match the developer's mental model, search becomes the only way in. If search is also weak, the whole site becomes hard to use, no matter how good the pages are.

The best docs sites test navigation against real dev tasks, not internal structure. Common entry points look more like "sign in," "send my first request," "handle an error," or "migrate from X."

The internal taxonomy can still live underneath as a reference layer, but it should not be the first thing a new visitor must decode.

5. The docs describe the product in isolation

Very few docs sites admit that readers are also weighing other options at the same time. That makes sense. Comparison content often feels like marketing's job, not docs' job.

In practice, though, developers making a choice during a trial use the docs as part of that review, whether the docs were written for that or not.

The sites that stood out had honest content about the comparisons developers were already making in their heads: how the product differs from the obvious leader, what tradeoffs come with a strange design choice, why a limit exists, and what the real workaround is.

Done well, this does not read like marketing. It reads like respect for the reader.

Done badly, or left out, that comparison happens somewhere else, often in a forum written by someone with less context than the product team has.

A short self-check

A simple self-audit can uncover most of these issues fast. Five questions usually get a team most of the way there:

• Can a script or AI agent pull every parameter, type, and requirement from the reference pages without relying on prose?
• Could two people on the team agree on which pages are tutorial, how-to, reference, and explanation?
• If the docs were searched for three different words for the same idea, would the results show term drift?
• Does the navigation match how a developer describes a problem, or how the engineering team describes the system?
• Somewhere in the docs, is there a clear answer to the question, "How is this different from the obvious alternative?"

None of these fixes needs a full rewrite. Most are structural. They are about reshaping what already exists, not writing all new content.

That is usually where the biggest gain is, and it is the first thing an effective documentation audit should surface.

If you need a second set of eyes to judge where your documentation stands across these five areas, that is the kind of work a documentation service like PaperKraft does.

Author

Harshil handles the technical side of the work. He wrote code long before he wrote docs, which is why the repo usually gets read before the outline does.

With five years writing docs for dev products, he has worked in-house at Atlan and Appsmith and as a freelancer for Twilio, DO, Neptune AI, Activeloop, and Middleware. At PaperKraft, he owns docs strategy and information architecture, decides what belongs in the outline before anyone writes a word, and joins every first client call.

Q&A

Question: Why does the article focus on machine-readable API documentation?

Short answer: Because AI agents and coding helpers are now often the first "reader" of API docs. They need clear structure to pull out endpoints, parameters, types, requirements, error codes, and rate limits. Clear prose still helps, but key API facts should live in fixed tables, typed schemas, and uniform examples, not in hidden paragraphs.

Question: What is the problem with mixing tutorials, how-to guides, reference pages, and explanation on one page?

Short answer: Each type serves a different need. A beginner needs a tutorial, a dev solving one task needs a how-to guide, someone debugging under pressure needs fast reference, and someone judging design choices needs explanation. When one page tries to do all of that, it usually helps no one well.

Question: How can term drift hurt otherwise good docs?

Short answer: Term drift makes readers stop and guess whether different words mean the same thing. For example, if one page says "workspace" and another says "project," a developer may waste time checking whether those are separate ideas or just different names for the same thing. One voice, one set of terms, and one code style make docs easier to trust.

Question: What does it mean for navigation to follow the task instead of the org chart?

Short answer: Task-based navigation is built around what developers want to do, such as "sign in," "send my first request," "handle an error," or "migrate from X." Org-chart navigation mirrors internal product structure, which may make sense to the team but confuse new users. The article argues that strong docs test navigation against real dev problems.

Question: Why should docs address product comparisons and tradeoffs?

Short answer: Developers often use docs to decide whether a product is the right pick during a trial or buying process. Honest notes on differences, limits, tradeoffs, and workarounds help readers make a smart choice. If the docs do not answer those questions, the comparison may happen somewhere else with less accurate context.