API documentation style guide (excerpt)

For developers and writers documenting our APIs. It’s short on purpose. If you remember only one thing, remember: write for the developer who is integrating at 11 p.m. before a launch.

Writing sample. This is an excerpt from a style guide I wrote for this portfolio, modelled on the kind I write for engineering teams. It isn’t any employer’s internal guide.

Voice

Use the second person and active voice. “You receive a webhook”, not “A webhook will be received”.
Use the present tense. “The endpoint returns”, not “The endpoint will return”.
Be direct, not cold. Leave out “simply”, “just” and “easily”. If it were easy, they wouldn’t be reading the docs.

Endpoint summaries

Start every endpoint with a one-sentence summary. Start with a verb, and describe the real-world outcome.

✗ Don’t	✓ Do
This endpoint is used for payout creation.	Sends money from your balance to a recipient.
Returns the dispute object.	Retrieves a dispute, including its status and evidence deadline.
API to cancel.	Cancels a payout that is still `pending`.

Parameter descriptions

Every parameter description answers, in this order:

What it is: “The ID of a verified recipient.”
Format or example: “For example, rcp_41Mzx9.”
Constraints or defaults: “Up to 35 characters. Defaults to your business name.”

Don’t repeat the type in the description. The Type column already says it’s a string.

Error messages

Every error message has three parts: what happened, why, and what to do next.

✗  Invalid request.
✓  The quote expired because more than 60 seconds passed. Create a new quote and try again.

Word list

Use	Don’t use	Why
participant	partner, member, client	“Participant” is the defined term in the network rules.
sign in	log in, login (as a verb)	Matches the UI.
select	click, tap, hit	Works for every device and input method.
settlement	clearing (in customer-facing docs)	Clearing and settlement are different steps. Use the one you mean.
e.g. → for example	e.g., i.e., etc.	Latin abbreviations are hard for non-native English readers and don’t translate well.

Code samples

Every sample must run. Test it before merging, and use sandbox credentials only.
Use realistic values ("September rent"), not foo and bar.
Show amounts in the smallest currency unit and explain the conversion once on the page.
Never include real keys, tokens or customer data. Use $ACCESS_TOKEN-style placeholders.

Was this page helpful?