English for Technical Documentation: Writing for Global Developer Audiences
Practical guidance for writing technical documentation in English — plain language principles, active vs passive voice, British vs American English choices, and inclusive language for global developer audiences.
Writing Documentation Is Writing for the Reader, Not the Writer
Technical documentation is written by experts and read by people trying to become experts. This fundamental asymmetry shapes everything about how good documentation is written: it must be accurate enough to satisfy the expert who wrote it, and clear enough to guide someone encountering the concept for the first time.
For non-native English writers, there is an additional challenge: the conventions of technical documentation English are specific, learnable, and different from both everyday written English and academic English. This guide covers the most important ones.
Plain Language Principles
Plain language means writing that a reader can understand the first time they read it, without rereading or looking up definitions. It does not mean writing simply — it means writing clearly.
Use Short Sentences
Long sentences with multiple clauses force readers to track more context than necessary. Split them.
- Before: “In order to authenticate the user, the application sends a POST request to the /auth endpoint, which returns a JWT token that must be included as a Bearer token in the Authorization header of all subsequent requests.”
- After: “To authenticate a user, send a POST request to /auth. The endpoint returns a JWT token. Include this token as a Bearer token in the Authorization header for all subsequent requests.”
Use Active Voice
Active voice names the actor. Passive voice hides it — which is useful in legal or audit writing, but harmful in documentation where the reader needs to know who does what.
| Passive (avoid in docs) | Active (prefer) |
|---|---|
| “The API key is generated by…" | "The platform generates an API key when…" |
| "The file must be named…" | "Name the file…" |
| "It is recommended that users…" | "We recommend you…” or “Configure the…” |
Exceptions: passive voice is appropriate when the actor is unknown, irrelevant, or intentionally omitted (“The log is written to /var/log/app.log” — it does not matter what writes it).
Use Imperative Mood for Instructions
Instructions should begin with a verb. This is the convention across all major documentation frameworks.
- “Open the configuration file.”
- “Set the TIMEOUT variable to 30.”
- “Restart the service.”
Not: “The configuration file should be opened” or “You will need to set the TIMEOUT variable.”
Active vs Passive Voice: When Each Is Right
The rule is not “always use active voice” — it is “use active voice when the actor matters.”
| Context | Voice | Example |
|---|---|---|
| Instructions | Active | ”Call the authenticate() method before making API requests.” |
| Describing system behaviour | Either | ”The scheduler runs every 60 seconds.” or “Tasks are scheduled every 60 seconds.” |
| Describing errors | Passive often works | ”An error is thrown when the token has expired.” |
| Describing configuration | Active | ”Set the log level to DEBUG to see verbose output.” |
British vs American English: Making a Consistent Choice
If you are writing documentation for a global developer audience, you need to make a consistent choice between British and American spelling conventions and stick to it. Mixing both in the same document looks careless.
| American English | British English |
|---|---|
| analyze | analyse |
| color | colour |
| center | centre |
| optimize | optimise |
| recognize | recognise |
| behavior | behaviour |
| labeled | labelled |
| authorization | authorisation |
At coderslingo.com, we use British English spelling throughout. When writing technical documentation for a British company or a company that has adopted British conventions, the above British forms are correct.
One exception: proper nouns and product names are not localised. “Color” in a CSS property name, a function name, or a UI label remains exactly as the product spells it, regardless of your documentation’s language convention.
Inclusive Language in Developer Documentation
Developer documentation increasingly follows inclusive language guidelines. Key principles:
| Avoid | Prefer |
|---|---|
| master / slave (in context of systems) | primary / replica, leader / follower |
| blacklist / whitelist | blocklist / allowlist |
| dummy variable | placeholder, stub |
| sanity check | smoke test, quick check |
| guys (for a group) | team, everyone, developers |
These choices are not just about social convention — they also improve clarity for non-native readers who may not be familiar with idiomatic terms.
Documentation Vocabulary for Non-Native Writers
| Term | When to use it |
|---|---|
| Prerequisite | A requirement that must be met before following the instructions |
| Refer to | To direct a reader to another section or resource |
| Ensure | To make certain that something is the case |
| Verify | To check that something is correct |
| Note: | A callout for non-critical information worth highlighting |
| Warning: | A callout for information that could cause problems or data loss |
| Caution: | A callout for information that could cause unexpected behaviour |
| Example | Illustrates usage — follow the actual example code immediately after |
| See also | Points to related resources |
Example Documentation Sentences
- “Before you begin, ensure that Docker is installed and running on your machine. To verify your installation, run
docker --version.” - “The following example demonstrates how to initialise the client with a custom timeout. Replace
YOUR_API_KEYwith the API key from your dashboard.” - “If the authentication token has expired, the API returns a 401 response. Refresh the token using the /auth/refresh endpoint.”
- “This page covers the core configuration options. For advanced network configuration, see Network Configuration.”
- “Use the allowlist parameter to restrict access to specific IP address ranges. Entries must follow the CIDR notation format (for example,
192.168.1.0/24).”
The Single Most Important Rule
Write for the reader who is in a hurry, has a deadline, and is frustrated because something is not working.
That reader will not read your introduction. They will search for the specific task they need to do. They will scan for code blocks. They will check the example first and the explanation second.
Write documentation that serves them — not documentation that demonstrates how thoroughly you understand the subject.