# The Note Left on the Door

An API is a promise that one system will answer another. The docs are the human side of that promise: a quiet explanation of what may be asked, and what will come back.

## What the name suggests

api-docs.md sounds technical, almost dry. Read it slowly and it becomes something kinder. Api is a doorway. Docs are the instructions written so a stranger can walk through without fear. The small ending, md, feels humble, like a file that does not need decoration to be useful.

People who write these pages rarely meet the people who read them. Still, the writing has to be trustworthy. A missing detail can cost someone an afternoon. A clear sentence can save one.

## A small philosophy

Good documentation is a form of hospitality. You do not need to impress the guest. You need to show them where the light switch is, and what happens if they turn it.

I picture a late evening in November 2026, a developer staring at a blank response. Somewhere else, months earlier, someone wrote a short page that said: here is the shape of the answer, here is what a mistake looks like, here is how to try again. That page is still doing its work.

Three habits keep the promise honest:

- Say what the thing actually does, not what you hoped it would do.
- Name the limits before someone discovers them the hard way.
- Leave the page easy to revise when the world changes.

## Why it matters

Interfaces change. Teams leave. The written note remains. It is not poetry, and it does not have to be. It is care, stored in plain language, waiting for the next person who needs a door to open.

*A clear page is a kindness that outlasts the person who wrote it.*