Professional English for API Documentation: Style, Register, and Structure

API documentation is some of the most read, most copied, and most quickly judged writing in the software industry. A developer evaluating your API will often decide within minutes whether to continue based on how clear and professional your docs are. Good API documentation requires not just technical accuracy but a specific kind of English: precise, consistent, and free of ambiguity. This guide covers the key decisions that determine whether your docs feel professional or amateurish.

---

Reference Docs vs Guides: Different Registers

API documentation comes in two primary forms, and they require different writing styles.

Reference Documentation

Reference docs describe exactly what each endpoint, parameter, method, or type does. The reader already knows what they want to achieve — they are looking up the specific detail. The register should be:

• Terse and precise — no unnecessary words
• Third person, present tense — “Returns an array of User objects”
• Consistent — use the same phrasing pattern for every endpoint
• Scannable — heavy use of tables, code examples, and labelled sections

Guides (How-to Docs and Tutorials)

Guides walk the developer through a task or concept. The register is slightly warmer and more explanatory:

• Second person, present tense — “To authenticate, send a POST request to…”
• More prose and context — explain why, not just what
• Progressive — build from simple to complex

A common mistake is mixing registers — writing guide-style explanatory prose in the middle of a reference endpoint description, or writing terse reference-style bullets in a guide where context is needed.

---

Verb Tense: The Present Tense Rule

API reference documentation uses the simple present tense throughout. This is a strong convention and deviating from it sounds immediately off.

Correct:

• “Returns an array of all active subscriptions.”
• “Accepts a JSON request body.”
• “Raises a ValidationError if the email field is missing.”
• “Throws a 404 Not Found error if the resource does not exist.”

Incorrect:

• “Will return an array…” (future tense — avoid in reference docs)
• “Returned an array…” (past tense — obviously wrong)
• “Should return…” (hedging — avoid, unless you specifically mean the spec, not the implementation)

The present tense convention treats the API as a fact of the world: it does this. It is not something that will do or might do.

---

Writing Parameter Descriptions

Parameter descriptions are one of the hardest things to write consistently. Here is a structure that works:

{name} (type, required|optional): Description. Default: {value}.

Examples

user_id (string, required): The unique identifier of the user. Must match the
authenticated user's ID or belong to an organisation the authenticated user
manages.

page (integer, optional): The page number for paginated results. Defaults to 1.
Minimum: 1.

include_archived (boolean, optional): When true, includes archived records in
the response. Defaults to false.

created_after (ISO 8601 datetime, optional): Returns only records created after
this timestamp. Example: 2026-01-15T09:00:00Z.

Key Rules for Parameter Descriptions

• Start with a capital letter, end with a period. Consistency matters.
• State the required/optional status — do not make the developer infer it.
• Specify the default value for optional parameters — always.
• Include constraints — min/max, format, allowed values. If there are allowed values, list them: “One of active, inactive, pending.”
• Give a format example for non-obvious types (dates, identifiers, patterns).

---

Returns, Throws, Raises: The Standard Verbs

Three verbs dominate API reference documentation for describing responses:

Verb	Use Case	Example
Returns	Describes the successful response body	”Returns a Payment object on success.”
Throws	Used in typed languages (Java, TypeScript) for exceptions	”Throws an AuthenticationException if the token is invalid.”
Raises	Used in Python documentation for exceptions	”Raises a ValueError if amount is negative.”
Responds with	HTTP-level description	”Responds with 200 OK and the updated resource.”

Choose one convention and be consistent within a codebase or docs set. Mixing “throws” and “raises” in the same documentation is a red flag for inconsistency.

---

A Full Endpoint Documentation Example

The following is an example of a well-structured endpoint document for a fictional REST API:

POST /v1/payments

Creates a new payment and returns the payment record. The payment is
processed asynchronously; the initial status is always `pending`.

Authentication: Bearer token required.

Request Body (application/json)

  amount        (integer, required):  The payment amount in the smallest
                                      currency unit (e.g., pence for GBP).
                                      Minimum: 1.

  currency      (string, required):   ISO 4217 currency code. One of:
                                      "GBP", "USD", "EUR".

  recipient_id  (string, required):   The ID of the recipient account.

  reference     (string, optional):   A client-defined reference string,
                                      returned unchanged in the response.
                                      Maximum 64 characters.

  idempotency_key (string, optional): A unique key to safely retry requests.
                                      If a payment with this key already
                                      exists, returns the original payment
                                      rather than creating a new one.

Returns

  201 Created — A Payment object:

    {
      "id": "pay_01J2K3L4M5",
      "status": "pending",
      "amount": 5000,
      "currency": "GBP",
      "recipient_id": "acc_9XY7Z",
      "reference": "invoice-2026-001",
      "created_at": "2026-06-15T10:00:00Z"
    }

Errors

  400 Bad Request    — Missing or invalid request parameters.
  401 Unauthorized   — Missing or invalid authentication token.
  404 Not Found      — The specified recipient_id does not exist.
  409 Conflict       — A payment with the given idempotency_key
                       already exists (returns the existing payment).
  422 Unprocessable  — Payment could not be processed (e.g., insufficient
                       funds in the source account).

---

Writing Consistent Prose in Guides

When writing guides rather than reference docs, a few additional English conventions apply:

• Use “you” to address the developer directly: “Before you can call the API, you need to obtain an API key.”
• Use imperatives for steps: “Send a POST request to /v1/auth/token. Include the client_id and client_secret in the request body.”
• Explain prerequisites upfront: “This guide assumes you have already completed the authentication setup.”
• Use transition phrases to link steps: “Once you have the token, you can use it to authenticate all subsequent requests.”
• Note edge cases explicitly: “If the user does not exist, the endpoint returns a 404. Handle this case before proceeding.”

---

Key Takeaways

• Use present tense throughout reference documentation — “Returns”, not “will return”.
• Distinguish reference docs (terse, third person, scannable) from guides (explanatory, second person, progressive).
• Parameter descriptions should always state type, required/optional, default, constraints, and format examples.
• Use Returns / Throws / Raises consistently — pick one convention per project and stick to it.
• A well-structured endpoint doc includes: description, authentication, request body parameters, success response, and error table.

Navigating the Nuances: Specifically for Non-Native Speakers

The principles of clear and concise API documentation – focusing on style, register, and structure – remain fundamentally the same regardless of your native language. However, the specific vocabulary and phrasing that feels ‘natural’ can vary dramatically. For developers whose first language isn’t English, it’s incredibly common to find yourself struggling with idioms, subtle grammatical differences, or simply not knowing the most precise term for a technical concept. This section aims to address some of those challenges directly, offering strategies and examples tailored to your situation.

One of the biggest hurdles is often understanding the register – the level of formality appropriate for different contexts. A detailed technical guide will naturally use a more formal register than a brief comment during code review. While aiming for precision is vital, over-formalizing can sound stilted and create distance between you and your colleagues. Conversely, overly casual language can diminish the authority of the documentation. Think about how you’d explain something to a colleague – that level of directness and clarity should inform your writing. For example, instead of saying “The endpoint is returning data,” consider “The API endpoint successfully returns data.” It’s subtly more professional without sacrificing readability.

Another common challenge arises when translating technical terms. Direct translations often don’t work; the English equivalents might be different, or the concept itself might require a slightly altered explanation. Don’t rely solely on online translation tools – they frequently produce awkward and inaccurate results. Instead, consult with colleagues who are fluent in both your native language and English to ensure accurate terminology. Furthermore, actively seek out and learn common industry jargon – this will significantly improve your understanding of conversations and documentation.

Finally, remember that active voice is generally preferred in technical writing. It’s more direct and easier to understand than passive constructions. Instead of saying “The data was processed,” write “The system processes the data.” This seemingly small change dramatically improves clarity and professionalism. Building this habit will pay dividends in all aspects of your communication, from PR descriptions to Slack conversations discussing potential issues. Don’t be afraid to ask for feedback – a quick check with a colleague can often highlight areas where your phrasing could be improved.