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.

1. Voice and tone

Our voice is clear, direct, helpful and calm.

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

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

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

4. Terminology

5. UI text conventions

• 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

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

• 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.

8. Headings and structure

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

• 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

• 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

12. Review checklist

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.