# Technical Writing Style Guide: [Organisation or product name]

> House style for technical documentation: voice, grammar, terminology,
> UI and code conventions, procedures, headings, links, accessibility,
> numbers and a review checklist. Based on common industry practice for
> technical writing; original wording. Replace every `[bracketed]` value
> and adapt the rules to your organisation.

<!--
Guidance: How to use this template
- A style guide is useful only if it is short enough to remember. Keep
  the rules that prevent real problems in your docs and delete the rest.
- Write each rule as a decision with an example, ideally a Do / Don't pair.
- Say what to follow when this guide is silent, for example a published
  general style guide or a dictionary, so writers do not invent rules.
- Automate checkable rules with a prose linter and record which ones are
  enforced in the review checklist.
-->

| Field | Value |
|---|---|
| Applies to | [User docs, API docs, release notes, UI text] |
| Version | [1.0] |
| Owner | [@docs-lead] |
| Fallback references | [Dictionary: Merriam-Webster / Oxford], [general style guide of your choice] |
| Spelling variant | [US English / UK English] |
| Last updated | YYYY-MM-DD |

## 1. Voice and tone

<!-- Guidance: Describe the voice in three or four traits, each with what it means in practice. Tone can shift by situation; the voice stays the same. -->

Our voice is **clear, direct, helpful and calm**.

| Trait | In practice | Do | Don't |
|---|---|---|---|
| Clear | Plain words, one idea per sentence | Select **Save**. | Kindly proceed to effectuate the save operation. |
| Direct | Address the reader as "you"; use the imperative for steps | Enter your API key. | The user should enter their API key. |
| Helpful | Tell readers what happens next and why it matters | Restart the service so the new port takes effect. | Restart the service. (when the reason is not obvious) |
| Calm | Neutral wording in errors and warnings, no blame or alarm | The file could not be uploaded. Check that it is under 25 MB. | Upload FAILED! You chose an invalid file. |

Adjust tone to the situation: brief and neutral in reference, encouraging
in tutorials, precise and serious in security warnings. Avoid humour in
error messages and in content that will be translated.

## 2. Audience

<!-- Guidance: Name the default reader and the assumptions writers may make. Pages for other audiences should say so at the top. -->

Unless a page says otherwise, write for [a technically capable person who
is new to our product]. Assume they can use a command line and a web
browser; do not assume they know our internal names, architecture or
abbreviations. Many readers use English as a second language and many
use machine translation, so prefer short sentences and common words.

## 3. Grammar and mechanics

<!-- Guidance: Keep only rules your writers actually get wrong. Each rule gets a Do / Don't pair. -->

| Rule | Do | Don't |
|---|---|---|
| Use active voice; name the actor | The installer creates a service account. | A service account is created. |
| Use present tense for product behaviour | The page shows your recent files. | The page will show your recent files. |
| Keep sentences under about 25 words | Split long sentences at "and" or "which". | One sentence with three clauses and two parentheses. |
| Use sentence case in headings and UI labels | Configure single sign-on | Configure Single Sign-On |
| Use the serial comma | files, folders, and links | files, folders and links |
| Spell out an abbreviation on first use | Recovery time objective (RTO) | RTO (with no expansion on the page) |
| Avoid "please" and "simply" in instructions | Enter your password. | Please simply enter your password. |
| Avoid Latin abbreviations | for example, that is | e.g., i.e. |
| Use contractions sparingly and consistently | do not / don't, as decided in [house rule] | Mixing both in one page |

[Adjust the serial comma and contraction rules to your house choice;
the point is to be consistent.]

## 4. Terminology

<!-- Guidance: List approved terms, terms to avoid, and product names with exact capitalisation. Link to the full glossary. -->

| Use | Avoid | Notes |
|---|---|---|
| sign in, sign out | log in, login (as a verb), log on | "Sign-in" as a noun or adjective |
| select | click on, hit, press (for UI controls) | "Press" is for keyboard keys |
| enter | type in, input (as a verb) | "Type" is fine for literal keystrokes |
| [ProductName] | [productname], [Product-Name] | Exact capitalisation, never possessive |
| allowlist, blocklist | whitelist, blacklist | Inclusive language, see 10 |
| primary, replica | master, slave | Inclusive language, see 10 |
| [Term] | [Avoid] | [Notes] |

## 5. UI text conventions

<!-- Guidance: Say how to refer to interface elements so readers can find them on screen. Match the UI exactly, including capitalisation. -->

- Put the names of UI elements in **bold**, exactly as they appear:
  Select **Export**.
- Show menu paths with a greater-than sign: **File > Export > PDF**.
- Do not name the control type unless it helps: "Select **Save**", not
  "Click the Save button".
- For keys, use the key name in monospace with `+` for combinations:
  `Ctrl+S`, `Cmd+Shift+P`.
- Describe location only when the element is hard to find: "In the
  upper-right corner, select **Settings**."
- When writing UI text itself: lead with the outcome, keep button labels
  to a verb and an object (**Delete file**), and say how to recover in
  error messages.

## 6. Code and technical elements

<!-- Guidance: Define how code, commands, file names and placeholders appear. Readers copy code, so precision matters more than elsewhere. -->

| Element | Format | Example |
|---|---|---|
| Inline code, commands, file names, paths, values | Monospace | Edit `config.yaml` and set `port` to `8080`. |
| Multi-line code | Fenced block with a language label | A fence opened with three backticks followed by `bash` |
| Placeholders | Upper case in angle brackets or square brackets, explained after the block | `<API_KEY>`: your key from **Settings > API**. |
| Command output | Separate block, labelled as output | A fence labelled `text`, introduced by "The output is:" |
| Prompts | Omit `$` in copyable commands | `npm install`, not `$ npm install` |

Code samples must run as shown, use realistic values (not `foo` and
`bar`), and never contain real secrets. Keep lines under 80 characters
where possible so they do not scroll.

## 7. Procedures

<!-- Guidance: Procedures are what readers use most. Set a firm pattern and apply it everywhere. -->

- Start with a heading that begins with a verb: "Create a project".
- State prerequisites before step 1.
- Use a numbered list; one action per step; no more than about 10 steps
  (split longer procedures).
- Put the location before the action: "In **Settings**, select **Users**."
- Put the result after the action, as a separate sentence: "The
  **Users** page opens."
- Put optional steps in the step itself: "Optional: add a description."
- Put warnings before the step they apply to, never after.

| Do | Don't |
|---|---|
| 1. In **Projects**, select **New project**. The dialog opens. | 1. Select New project in Projects which opens a dialog where you can also add a description if you want and then save. |

## 8. Headings and structure

<!-- Guidance: Headings are navigation. Make them predictable and scannable. -->

| Page type | Heading style | Example |
|---|---|---|
| Task (how-to) | Imperative verb | Configure single sign-on |
| Concept | Noun phrase | Workspaces and permissions |
| Reference | Name of the thing | Configuration settings |
| Troubleshooting | Symptom in the reader's words | Import stops at 99% |

Use one H1 per page. Do not skip levels. Do not put two headings in a
row without text between them. Keep headings under about eight words and
avoid code formatting in headings where possible.

## 9. Links and cross-references

<!-- Guidance: Links should tell readers where they go before they click. -->

- Make link text describe the destination: "see [Configure SSO]", not
  "click [here]".
- Link the first relevant mention on a page, not every mention.
- Prefer relative links within the docs so they survive domain changes.
- Mark links that leave the documentation site or download a file:
  "[Download the sample CSV (12 KB)]".

## 10. Accessibility and inclusive language

<!-- Guidance: Accessible docs serve everyone, including people using screen readers, magnifiers or translation. Inclusive wording avoids excluding or stereotyping readers. -->

- Give every image alt text that states what the image shows and why it
  matters. Decorative images get empty alt text.
- Never rely on colour or position alone: not "the red button" or "the
  link on the right", but its label.
- Use tables for data, not for layout, and give them header rows.
- Use gender-neutral language: "they" for an unknown person, "people"
  rather than "guys".
- Avoid ableist idioms and violent metaphors: "check" rather than
  "sanity check", "stop" rather than "kill" where the UI allows.
- Avoid idioms, sports references and culture-specific jokes.

## 11. Numbers, dates, times and units

<!-- Guidance: Pick one format for each and apply it everywhere. Ambiguous dates cause real errors across regions. -->

| Item | Rule | Example |
|---|---|---|
| Numbers | Numerals for 10 and above, and for all measurements | 3 projects, 12 users, 5 MB |
| Large numbers | Comma thousands separator in English text | 10,000 requests |
| Dates | ISO 8601 in tables and logs; month name in prose | 2026-10-21; 21 October 2026 |
| Times | 24-hour clock with time zone | 14:30 UTC |
| Units | Space between number and unit; SI prefixes | 25 MB, 500 ms, 2 GHz |
| Ranges | Use "to" in prose | 1 to 64 jobs |
| Percentages | Numeral with % sign, no space | 99.9% |

## 12. Review checklist

<!-- Guidance: The checklist the author and reviewer both use. Mark which items an automated linter enforces. -->

| # | Check | Automated |
|---|---|---|
| 1 | Page has one type (tutorial, how-to, reference or explanation) | No |
| 2 | Title and headings follow section 8 | Partly |
| 3 | Every procedure was tested on the current version | No |
| 4 | Active voice, present tense, sentences under about 25 words | Yes (linter) |
| 5 | Terms match section 4 and the glossary | Yes (linter) |
| 6 | UI names in bold and match the product exactly | No |
| 7 | Code samples run, have language labels, contain no secrets | Partly |
| 8 | Links work and have descriptive text | Yes (link checker) |
| 9 | Images have alt text; no meaning conveyed by colour alone | Partly |
| 10 | Numbers, dates and units follow section 11 | Yes (linter) |
| 11 | Inclusive language rules in section 10 are met | Yes (linter) |

## Standard and licence note

Based on common industry practice for technical writing style guides.
This template is original text written for this collection and does
not reproduce any published corporate style guide. Template licence: MIT.