Technical Writing Style Guide Template

Tech writing style guide – voice, grammar do/don't, terminology, UI and code conventions, procedures, inclusive language

文档与支持标准style guide technical更新于 2026年10月20日

在编辑器中打开下载 .md

使用方法: Use to set house style for docs, API docs and UI text. Keep only rules your writers actually break, each with a Do and Don't example, and name a fallback guide. The main pitfall is a guide too long for anyone to remember.

预览

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.

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

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

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

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

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

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

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

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

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

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

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

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