I have watched three separate teams this year spend weeks debating whether their API docs should be OpenAPI, GraphQL SDL, or some bespoke format that one engineer really likes. None of those teams shipped a single page of documentation.

The format debate is a procrastination technique. It feels productive because it involves architecture diagrams and tooling evaluations. But while you are deciding between Redoc and Swagger UI, your users are reading your source code to figure out how authentication works. They are grepping through test files for examples. They are DMing your engineers at 2am asking what the rate limit is.

Here is the uncomfortable truth: a hastily written README with three curl examples and a note about error codes will save your users more time than a pristine OpenAPI spec that does not exist yet. Perfection is the enemy of usefulness.

I am not saying tooling does not matter. It does. Eventually. But the obsession with finding the right format before writing a single word is backwards. Documentation is not a schema problem. It is a writing problem. Someone needs to sit down and explain what the API does, how to call it, and what to do when it breaks.

What good enough looks like

Before you build anything else, write a single markdown file that covers these six things:

Base URL and versioning. Where does the API live? How do version changes work?
Authentication. Exactly how to get a token or key. With a copy-pasteable example.
One complete request/response. Pick your most common endpoint. Show the full curl command. Show the full JSON response. Annotate the interesting fields.
Error format. What does a 400 look like? A 401? A 500? Show the shape.
Rate limits and pagination. State the numbers. Show how pagination works.
A working code example. One language. Five lines. Something a developer can paste and run.

That is it. Six sections. You can write this in an afternoon. You can generate the curl examples from your test suite. You do not need a committee, a style guide, or a CI pipeline for docs generation.

I have seen this approach cut onboarding time by half in practice. New developers stop asking the same five questions in Slack. Integration timelines drop from days to hours. And once the foundation exists, you can iterate. Add more endpoints. Improve formatting. Migrate to a doc tool. But you cannot iterate on nothing.

The teams that win at developer experience are not the ones with the best documentation toolchain. They are the ones that actually wrote something down.

So here is the challenge. If your API does not have public documentation right now, close whatever documentation planning meeting is on your calendar this week. Open a text file. Write the six sections above. Ship it before lunch. Your users will thank you, and your future self will stop apologising for the gap.