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.