Style Guide · Content Governance

Knowledge Base Style Guide (excerpt)

Audience: KB authors, global support
Applies to: All KB articles
Doc ID: GOV-STYLE-001
Review cycle: Quarterly

1.0Why this guide exists

A knowledge base written by forty authors should read like it was written by one. Consistency isn't cosmetic: when every article follows the same structure and voice, support agents find answers faster, translations cost less, and search works better. This guide is the single source of truth for how we write. When it conflicts with personal preference, the guide wins.

2.0Voice and tone

Write like a knowledgeable colleague, not a policy manual. Our voice is direct, calm, and helpful.

Write thisTo reset your password, select Forgot password on the sign-in page.

Not thisUsers who have forgotten their credentials may initiate the password-reset workflow via the authentication portal.

Use second person. Address the reader as "you." Reserve "we" for the company taking an action ("we send a confirmation email").
Use active voice. "The system locks your account after five attempts," not "the account will be locked."
One idea per sentence. If a sentence needs a semicolon, it usually wants to be two sentences.

3.0Article structure

Every article uses the same skeleton so readers always know where to look:

Section	Purpose	Length
Title	Task-based, starts with a verb: "Reset your password."	≤ 60 characters
Summary	Who this article is for and what it covers.	1–2 sentences
Steps	Numbered procedure. One action per step.	≤ 10 steps; split longer tasks
Result	What the reader should see when it worked.	1 sentence
Related articles	3–5 links, most relevant first.	List only

Rule of thumb If an article answers more than one question, it's more than one article. Split it and cross-link.

4.0Writing steps

Write this3. Select Payroll > Direct deposit, then select Add account.

Not this3. Go into the payroll area of the system where you should be able to locate the direct-deposit settings and add your account.

Start each step with the action verb. Select, enter, open, confirm.
Bold every UI element the reader interacts with, exactly as it appears on screen.
Put conditions before actions. "If you have more than one account, select the account first" — the reader needs the "if" before the "do."

5.0Terminology

Use one term per concept, everywhere. The glossary below is authoritative; regional teams must not substitute local variants, because inconsistent terms fragment search results.

Use	Instead of	Notes
sign in	log in, login (verb)	"Login" is acceptable only as a noun/adjective: "the login page."
select	click, tap, press	Device-neutral; works for desktop, mobile, and translation.
manager	supervisor, lead	Matches the term used in the HR system itself.
time off	PTO, leave, vacation	Region-neutral umbrella term; name specific leave types only when the policy differs.

6.0Writing for a global audience

Avoid idioms and culture-bound references. "Touch base," "out of pocket," and sports metaphors don't translate.
Spell out dates. Write "3 April 2026," never "04/03/2026" — that string means two different days depending on the reader's region.
Keep sentences under 25 words. Short sentences translate more accurately and cost less to localize.