Complete English Guide for Technical Writers

Why English Matters for Technical Writers

Technical writing is the one IT discipline where English is not a supporting skill — it is the entire deliverable. A backend developer's code can compile even if their comments are imperfect. A technical writer's document has failed the moment a reader cannot understand it, regardless of how technically accurate the underlying information is. Precision, clarity, and consistency in English are not stylistic preferences for a technical writer; they are the measure of whether the job has been done at all.

The English required for technical writing spans an unusually wide range of registers within a single role. The same writer might draft a beginner-friendly tutorial in one hour and a terse, dense API reference page in the next — two documents with almost opposite stylistic rules, both written in "clear English" but calibrated for completely different reader needs. A technical writer must also conduct interviews with engineers who explain concepts imprecisely, then translate that imprecise explanation into unambiguous, testable documentation. This requires active listening in English, the ability to ask clarifying questions without appearing to slow the engineer down, and the skill of restating a complex answer back for confirmation.

Technical writers also work inside the same tools as developers — Markdown, Git, pull requests, CI pipelines — which means they must be fluent in reading English-language code comments, commit messages, and pull request discussions, even when they are not writing code themselves. A misread commit message or an ambiguous pull request comment can result in documentation that describes a feature that was actually reverted, or that misses a breaking change entirely.

This guide covers the specific English vocabulary and communication patterns of professional technical writing: the Diataxis documentation framework that underpins how modern docs sites are organised, the precise register of API reference writing, the interview technique used to extract accurate information from subject matter experts, the plain-language principles that make complex information accessible, the docs-as-code workflows that put writers inside engineering pipelines, the conventions of changelog and release-note writing, and the microcopy skills increasingly expected of writers working on product UX.

Section 1: The Diataxis Documentation Framework

Diataxis, created by Daniele Procida, is now the dominant mental model for organising technical documentation in English-language software projects, adopted by Django, the Linux kernel, Cloudflare, and hundreds of other documentation sites. It divides all documentation into four distinct modes, each answering a different reader need, and each requiring a different English register.

The Four Modes and Their Registers

Tutorials are learning-oriented: they take a complete beginner through a guided experience where the goal is building confidence, not completing a real task. Tutorial English is warm, encouraging, and reassuring: "Don't worry if this doesn't make complete sense yet — by the end of this tutorial you will have a working application and a much clearer picture of how the pieces fit together." Use "we" and "let's" to create a sense of shared progress: "Let's start by creating our first component."

How-to guides are task-oriented: they help a competent user accomplish a specific real-world goal as efficiently as possible. How-to English is terse and assumes competence: "To rotate API keys without downtime: 1. Generate a new key in the dashboard. 2. Update your application configuration to use both keys. 3. Deploy the change. 4. Revoke the old key after confirming traffic uses the new one." No encouragement, no explanation of why — just the steps.

Reference is information-oriented: comprehensive, accurate, and structured for scanning rather than reading start to finish. Reference English is neutral, consistent, and exhaustive: every parameter is documented in the same format regardless of how commonly it is used. "timeout (integer, optional, default: 30) — The maximum time in seconds to wait for a response before raising a TimeoutError." Explanation is understanding-oriented: it provides context, discusses alternatives, and answers "why" rather than "how." Explanation English is discursive and may use "you might wonder why..." framing to anticipate reader questions.

The most common documentation-quality failure is mixing modes within a single document — adding a paragraph of explanation into the middle of a how-to guide, or writing a tutorial that reads like a reference page. Diagnosing and fixing this mixing is one of the highest-value skills a technical writer develops, and describing the problem precisely in English ("this how-to guide has drifted into explanation-mode in the third section — the reader came here to complete a task, not to understand the underlying architecture") is itself a professional skill worth practising.

Section 2: API Documentation Writing

API documentation is the most formally structured genre of technical writing English, and the genre where precision matters most — a single ambiguous parameter description can cost a developer hours of debugging. It has its own well-established vocabulary and register conventions.

Endpoint and Parameter Description Language

Endpoint descriptions follow a fixed pattern: verb + resource + qualifying detail. "Retrieves a paginated list of active users, filtered by the optional role query parameter." Not "This endpoint gets users" — precision requires stating the HTTP verb's semantic meaning, the resource, and every relevant qualifier. Parameter tables use consistent, parallel phrasing for every row: type, whether required or optional, default value, and a single clear sentence describing behaviour, not just a restatement of the name. Weak: "limit — the limit." Strong: "limit (integer, optional, default: 20, max: 100) — The maximum number of items to return per page. Values above 100 are capped silently."

Error documentation deserves the same rigour as success responses. Every documented error should state: the HTTP status code, the machine-readable error code, when it occurs, and what the client should do. "429 Too Many Requests — Returned when the client has exceeded the rate limit for this endpoint. The Retry-After header indicates the number of seconds to wait before retrying." OpenAPI (Swagger) specification vocabulary — schema, operationId, requestBody, components, $ref — is now assumed fluency for anyone documenting REST APIs professionally.

Code Sample Conventions

Code samples in API documentation follow their own English conventions: comments explain intent, not syntax ("// Retry with exponential backoff on 429" rather than "// this is a for loop"), variable names in samples should be realistic rather than generic (customerId rather than x), and every sample should be immediately runnable — copy-paste failures are one of the most common and most damaging documentation defects. Multi-language code sample sets require consistent example data across languages so a reader comparing the Python and Node.js tabs sees the same customer ID and the same expected output.

Section 3: SME Interviews & Information Extraction

Technical writers rarely have first-hand knowledge of every system they document. Extracting accurate information from a subject matter expert (SME) — usually a busy engineer who thinks in code, not prose — is a distinct communication skill with its own English patterns.

Structuring the Interview

Open an SME interview with a clear scope statement so the engineer knows exactly what you need and how much time it will take: "I'm documenting the new webhook retry behaviour for the changelog. I have three questions and should need about 15 minutes." Use funnel questioning: start broad ("Can you walk me through what changed in this release?") then narrow to specifics ("When you say it retries with backoff — what's the exact backoff schedule? Is it capped?"). Avoid leading questions that assume an answer: not "So it retries three times, right?" but "How many times does it retry, and under what conditions does it stop?"

Restating for Confirmation

The single most valuable phrase in SME interview English is the reflective restatement: "Let me make sure I've got this right — the webhook retries up to five times with exponential backoff starting at one second, and gives up after five minutes total, at which point it marks the delivery as failed and requires manual replay. Is that accurate?" This surfaces misunderstandings before they are published, and experienced writers use it after every substantive answer, not just at the end of the interview. When an engineer's answer is technically correct but too dense to use directly, translate and reflect it back in plainer language for confirmation rather than publishing the jargon verbatim.

When an SME gives a vague or hedged answer ("it should generally work most of the time"), a technical writer must push for precision without seeming adversarial: "That's helpful context — for the documentation I need something more specific: is there a defined SLA, or is 'most of the time' the accurate description we should publish? If it's the latter, I'll phrase it as a known limitation rather than a guarantee." This kind of tactful precision-seeking is a core professional skill.

Section 4: Plain Language & Style Guides

Plain language means writing that a reader understands on the first pass, without re-reading. It is a well-defined discipline in English-language technical writing, not a vague aspiration, and it has concrete rules that a technical writer applies and defends in editorial discussions.

Core Plain Language Rules

Use active voice by default: "The server rejects the request" rather than "The request is rejected by the server" — active voice states who does what, which is almost always clearer and shorter. Prefer common words over Latinate jargon where meaning is unaffected: "use" rather than "utilise," "help" rather than "facilitate," "start" rather than "commence." Put the most important information first in a sentence and in a paragraph — readers scan, and the first eight words of a sentence receive most of the attention. Write short sentences for procedural content; one sentence per step in a numbered list. Replace vague quantifiers with numbers: not "the request may take a while" but "the request typically completes within 200–500ms."

Applying and Defending a Style Guide

A style guide (Google Developer Documentation Style Guide, Microsoft Writing Style Guide, or an internal guide) governs word choice, tone, capitalisation, and terminology consistency across a docs site. Technical writers use style-guide language in editorial reviews: "Per our style guide, we use 'sign in' not 'log in' for consistency with the product UI — can you update this PR?" / "This section uses second person ('you can configure...') while the rest of the page uses imperative mood ('configure...') — let's pick one for consistency." Defending a style choice to an engineer who disagrees requires calm, evidence-based language: "I understand the preference for 'authenticate,' but our user research showed the target audience — junior developers — found 'sign in' clearer and it matches the button label in the product."

Section 5: Docs-as-Code & Version Control for Documentation

Modern technical writers work inside the same Git-based workflows as software engineers — a practice known as "docs as code." This requires fluency in engineering-adjacent English that many writers were not trained in: pull request descriptions, code review comments, and CI pipeline vocabulary applied to prose rather than code.

Writing Documentation Pull Requests

A documentation pull request description should state the reader-facing change, not just the file change: "Updates the authentication guide to reflect the new OAuth 2.1 flow released in v4.2. Removes the deprecated implicit grant section. Adds a migration note for teams still using the old flow." When requesting review from an engineer, be specific about what kind of feedback you need: "I'd appreciate a technical accuracy check on the code samples in section 3 — I haven't tested the retry logic myself." This distinguishes a request for technical review from a request for prose/style review, which most engineers are not well positioned to give.

Responding to review comments on documentation follows the same collaborative register as code review: "Good catch — I'll clarify that the rate limit is per API key, not per account." / "I'd push back gently here: the current phrasing matches our established style guide's convention for describing async operations — happy to discuss further if you feel strongly." Docs-as-code vocabulary includes: "content linting" (automated style and grammar checks in CI), "broken link checker," "docs preview build" (a staging deployment of the docs site generated from a pull request), and "docs deployment pipeline."

Section 6: Release Notes & Changelog Writing

Changelogs and release notes are read under time pressure by people deciding whether an update affects them — this makes them one of the most compressed and demanding genres of technical writing English.

Changelog Entry Conventions

Following the widely adopted "Keep a Changelog" convention, entries are grouped under standard headings: Added, Changed, Deprecated, Removed, Fixed, and Security. Each entry is a single, scannable line starting with a past-tense verb: "Added support for webhook signature verification using HMAC-SHA256." / "Fixed a race condition causing duplicate email notifications when two updates occurred within the same second." Breaking changes must be flagged unambiguously, often with a dedicated "BREAKING CHANGES" section or a ⚠️ marker, and must state the migration action required: "BREAKING: The legacy_id field has been removed from the user object. Clients depending on this field must migrate to uuid before upgrading."

Release Note Register for Different Audiences

Developer-facing release notes are terse and technical: "Fixed: POST /v2/orders now correctly returns 409 Conflict instead of 500 when a duplicate idempotency key is submitted." Customer-facing release notes for a non-technical audience translate the same fix into outcome language: "We fixed an issue where retrying a payment could occasionally show an unexpected error message." The underlying fact is identical; the register and vocabulary are calibrated entirely to the reader.

Section 7: UX Writing & Microcopy

Increasingly, technical writers are asked to own or contribute to product microcopy — error messages, empty states, button labels, confirmation dialogs — a discipline with tighter word budgets and higher scrutiny than long-form documentation, since microcopy is read by every single user of a product.

Error Message Writing

A good error message in English states what happened, why (if known), and what the user should do next, in that order, without blaming the user or the system unnecessarily. Weak: "Error: invalid input." Strong: "This email address is already registered. Try signing in instead, or use a different email to create a new account." Avoid technical jargon in user-facing errors: "Something went wrong on our end. We've been notified and are looking into it. Please try again in a few minutes" rather than exposing a stack trace or internal error code to an end user.

Buttons, Empty States, and Confirmations

Button labels use verb-first, specific phrasing rather than generic labels: "Delete project" rather than "OK" for a destructive confirmation, so the action is unambiguous even if a user does not read the full dialog text. Empty states — the screen a user sees before any data exists — should be encouraging and actionable rather than merely descriptive: "You haven't created any projects yet. Create your first project to get started" rather than "No projects." Destructive action confirmations must state the specific consequence: "Delete 'Q3 Marketing Campaign'? This will permanently remove all 14 associated tasks. This cannot be undone."

Most Useful Vocabulary & Phrases for Technical Writers

Recommended Learning Path for Technical Writers

1. 1

   Plain Language in Technical Writing exercises

   The foundational skill for every other section in this guide — active voice, common words, and scannable structure.

2. 2

   Diataxis Documentation Framework exercises

   Learn to diagnose and organise documentation into tutorials, how-to guides, reference, and explanation.

3. 3

   Writing for API Documentation exercises

   The most formally structured genre — endpoint descriptions, parameter tables, and error documentation.

4. 4

   Documentation Types exercises

   RFCs, runbooks, ADRs, and other structured documentation formats used across engineering teams.

5. 5

   Knowledge Base & Internal Docs Writing exercises

   How-to guide writing, runbook language, and onboarding documentation for internal audiences.

6. 6

   Code Review Language exercises

   Directly transferable to reviewing and responding to feedback on documentation pull requests.

7. 7

   UX Writing & Microcopy exercises

   Error messages, empty states, and confirmation dialog language for writers contributing to product UX.

8. 8

   Technical Writer Interview Questions

   Practice for technical writing interviews — portfolio discussion, editorial judgement, and SME collaboration questions.

Exercise Sets for Technical Writers

Practise the vocabulary and communication patterns covered in this guide with these focused exercise sets: