English Style Guides for Developer Documentation: What Every Tech Writer Should Know

When you write developer documentation — API references, tutorials, README files, or onboarding guides — the style choices you make directly affect how quickly developers understand and trust your content. The major technology companies have published detailed style guides that reflect years of research into what works. Understanding the core principles of these guides will improve your documentation immediately.

The Major Style Guides

Three style guides dominate developer documentation:

Google Developer Documentation Style Guide — publicly available and comprehensive. Emphasises clarity, sentence-level simplicity, and active voice. Widely adopted by open-source projects and startups.

Microsoft Writing Style Guide — used across Microsoft products and developer documentation. Places strong emphasis on a friendly, approachable tone alongside technical precision. Introduced the influential guidance on using “you” instead of the developer/user.

Apple Style Guide — governs documentation for Apple platforms. Notable for its precision and consistency requirements, particularly around product name formatting and user-interface terminology.

All three guides share core principles: active voice, second person, short sentences, and plain language over jargon.

Active Voice

Active voice makes documentation clearer and more direct. In active sentences, the subject performs the action. In passive sentences, the subject receives the action.

Why it matters: Passive constructions hide who is responsible for an action and are harder to scan quickly.

Before (passive): “The access token is passed to the endpoint by the client.” After (active): “The client passes the access token to the endpoint.”

Before (passive): “A 404 error will be returned if the resource is not found.” After (active): “The API returns a 404 error if the resource does not exist.”

Passive voice is acceptable when the actor is truly unknown or irrelevant: “The record was deleted.” But if you know who does the deleting, say so.

Second Person Usage

Both Google and Microsoft recommend writing directly to the developer using “you.” This makes documentation feel like a conversation rather than a formal specification.

Before (impersonal): “Developers should ensure that the configuration file is present before initialising the client.” After (second person): “Ensure the configuration file is present before you initialise the client.”

Before (third person): “The user can authenticate using an API key or OAuth 2.0.” After (second person): “You can authenticate using an API key or OAuth 2.0.”

Avoid “one” as a pronoun substitute: “One should configure the environment before proceeding” is formal to the point of being unfriendly.

Inclusive Language

All three major style guides now include guidance on inclusive language, particularly around disability, gender, and problematic technical terminology.

Avoid ableist metaphors:

• “Sanity check” → “Quick check” or “Validation check”
• “Dummy variable” → “Placeholder variable” or “Example variable”

Replace loaded infrastructure terms:

• “Master/slave” → “Primary/replica” or “Leader/follower”
• “Whitelist/blacklist” → “Allowlist/denylist”

Gender-neutral language:

• Use “they/their” as a singular pronoun when the person’s gender is unknown.
• Avoid “he or she” constructions.
• Prefer role names over gendered terms: “the developer” not “the man who builds it.”

Sentence Length and Scanability

Developer documentation is typically scanned rather than read linearly. Short sentences and clear structure help readers find what they need.

Guidelines:

• Aim for an average sentence length of 15–20 words.
• Put the most important information first in each sentence.
• Use bulleted or numbered lists for steps and options.
• Use code blocks for all code, commands, and file paths.

Before (long, complex): “In order to ensure that the authentication process completes successfully, it is necessary for developers to make sure that the redirect URI that has been registered in the application configuration matches exactly the redirect URI that is being passed in the OAuth request.”

After (short, clear): “The redirect URI in your OAuth request must exactly match the redirect URI registered in your application settings. A mismatch causes the authentication to fail.”

Before/After Style Corrections

Here are five complete before/after corrections showing common documentation mistakes and their improvements:

1. Passive + impersonal → Active + second person Before: “The package can be installed by running the install command.” After: “Install the package by running npm install my-package.”

2. Jargon → Plain language Before: “Utilise the aforementioned methodology to instantiate the configuration object.” After: “Use this approach to create the configuration object.”

3. Loaded terminology → Inclusive alternative Before: “Configure the master node to accept connections from slave nodes.” After: “Configure the primary node to accept connections from replica nodes.”

4. Buried action → Front-loaded instruction Before: “If you have completed the previous steps and the service is running, you can now make your first API request.” After: “Make your first API request once the service is running.”

5. Vague → Specific Before: “Make sure the environment is set up correctly.” After: “Set the DATABASE_URL and API_KEY environment variables before starting the server.”

Choosing a Style Guide for Your Project

If you are working on an open-source project, the Google Developer Documentation Style Guide is the safest choice — it is free, widely referenced, and comprehensive. If you work within a Microsoft ecosystem, adopt the Microsoft Writing Style Guide. If you are writing for Apple platforms, follow the Apple Style Guide for product-specific terminology.

Whichever guide you choose, consistency matters more than perfection. A team that follows one guide imperfectly is producing better documentation than a team with no guide at all.

Navigating Nuances: English for Developers Beyond the Basics

The core principles of clear and concise technical writing – active voice, direct addressing, and careful word choice – are universally valuable. However, when developers from diverse linguistic backgrounds collaborate, subtle differences in phrasing can lead to misunderstandings and friction, even if the intent is perfectly clear. It’s not simply about adhering to a style guide; it’s about recognizing that different ways of expressing ideas carry different connotations, and actively working towards shared understanding. A common pitfall for non-native English speakers is over-reliance on literal translations from their native languages, which can result in overly formal or complex sentence structures. For instance, a phrase perfectly acceptable in Japanese might sound incredibly verbose and awkward when directly translated into English.

Consider this scenario: Sarah, a developer new to the team, submits a pull request with the description: “I have implemented the feature X, that is related to Y.” This reads stiffly and lacks clarity. While technically correct, it’s not the most effective way to communicate her work. A native English speaker would likely say, “I’ve implemented the X feature, which addresses Y.” The addition of “which” clarifies the relationship between the two elements and streamlines the sentence. Similarly, during a code review, a comment like “The function is not working correctly” could be softened to “The function isn’t producing the expected results,” acknowledging that there might be multiple potential causes for the issue.

Another frequent challenge arises in Slack conversations. A developer struggling with a particular concept might type: “I have tried to use this method, but it doesn’t work.” This is grammatically acceptable but could benefit from more specific feedback. A better approach would be “I’ve been trying the methodName function, and I’m encountering [specific error message or unexpected behavior]. Could you suggest an alternative?” The inclusion of details – the specific function name, the exact error message – immediately provides valuable context to the reviewer and allows for a more targeted solution. This level of detail is often perceived as overly verbose by native English speakers, but it’s crucial when communicating with colleagues who may need extra support navigating the nuances of professional English.

Finally, don’t be afraid to ask for clarification. If you’re unsure how something is phrased or what a particular term means within your team’s workflow, asking politely is always better than assuming. Phrases like “Could you elaborate on what you mean by ‘optimizing performance here’?” or “I want to make sure I understand – are we aiming for [specific metric]?” demonstrate engagement and a willingness to learn, fostering a more collaborative environment. Remember, effective communication isn’t just about what you say, but how you say it, and building that shared understanding is key to successful technical collaboration.