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.
Bridging the Gap: Supporting Non-Native Speakers
Writing clear and effective technical documentation is a challenge regardless of your native language. However, when developers whose first language isn’t English are involved, the complexities multiply. It’s not just about grammatical accuracy; it’s about navigating subtle nuances in phrasing, understanding common idioms, and recognizing how certain vocabulary choices might be misinterpreted. The goal isn’t to dumb down the technical content – quite the opposite, we want precision – but to ensure everyone understands the intent behind the words. A well-written document removes ambiguity and fosters collaboration, regardless of individual language proficiency.
One common area of difficulty for non-native speakers is understanding feedback within a code review context. Consider this Slack message: “This change introduces a potential race condition. Consider adding a mutex to protect the shared resource.” The directness can feel blunt, especially if the recipient isn’t accustomed to such concise technical criticism. It’s not necessarily incorrect, but it lacks the softening language that might be naturally present in more conversational English. A helpful follow-up could be: “This change introduces a potential race condition – we need to ensure data consistency when multiple threads access this shared resource simultaneously. Adding a mutex would provide synchronization and prevent these issues. Could you explore adding one here?” The extra phrasing provides context, suggests a specific solution, and frames the issue in terms of broader system design principles, which is often more accessible than simply pointing out an immediate problem.
Similarly, crafting effective Pull Request descriptions requires careful consideration. A terse description like “Fix bug” leaves room for interpretation. A better approach would be: “Resolve Issue #123 – Incorrect calculation of user discount due to integer overflow. This PR implements a long-integer data type to address the issue and includes unit tests to verify the fix.” The detailed explanation allows reviewers to quickly grasp the problem, the solution, and the verification steps. It also demonstrates a proactive approach – the developer isn’t just fixing something; they’re documenting why it was broken and how it’s now resolved.
Finally, remember that patience and encouragement are crucial. Offering constructive feedback in a supportive manner can significantly boost confidence and improve communication. Framing suggestions as “consider” or “perhaps exploring” rather than direct commands (“you must”) can make a huge difference. Actively soliciting clarification – “Could you explain your thinking behind this approach?” – demonstrates a genuine desire to understand their perspective and build a stronger working relationship. Focus on the outcome – clear communication – more than rigidly enforcing every grammatical rule.