Knowledge base style guide

A KB style guide is the one standard every article in your help center is written to. Adopt it once and a how-to drafted by a week-two hire reads like one your best writer produced — same shape, same voice, the same word for the same thing every time. That sameness isn't cosmetic: it's what lets a stressed customer scan an article in ten seconds and trust it enough to act.

It earns its keep because the KB is the first thing customers reach for. Across industries, 81% of customers try to handle a problem themselves before contacting a person (Harvard Business Review, 2017), yet only 9% report fully resolving their issue through self-service (Gartner, 2019). A large part of that gap is content that exists but can't be found, read, or acted on. A style guide won't create coverage you don't have — audit that separately — but it fixes the writing that turns a visit into a resolution instead of a ticket.

Fill in every [bracket] once. Those are your house choices. Everything else is the rule.

Your house choices (set once)

Voice and tone

Write to one person trying to get one thing done, right now. Not a manual, not marketing.

Never blame the reader — "simply", "just", and "obviously" all imply they're slow. Never promise a timeframe the product can't keep.

The article skeleton

Every article follows this shape. Fill it in; delete parts a given article doesn't need, but don't reorder them.

# [What the customer wants to do, in their words]

[One sentence: who this is for and what they'll have when they're done.]

**Before you start**
- [prerequisite / permission / plan needed]

## Steps   (or: ## Fix)
1. [Action verb first. One action per step.]
2. …

**Did it work?** [How the customer confirms success.]

**If it didn't** [The top one or two failure cases + what to do.]

**Related**
- [link to the next thing they'll need]

Titles and headings

The title is what a customer would type or say — a task or a symptom, not a feature name.

Headings inside an article are scannable signposts: someone skimming only the bold headings should still land on their spot. Use sentence case everywhere — "Reset your password", not "Reset Your Password".

Article types

Pick one type per article. Mixing a concept explainer into a how-to is why articles get long and get abandoned.

Writing steps

• Start every step with a verb: Click, Enter, Select, Turn on.
• One action per numbered step. If a step contains an "and", split it.
• Bold exactly what's on screen: Click Settings → Billing.
• State where a control is only when it's genuinely hard to find.
• Put the result after the action when it isn't obvious: "Click Publish. The article goes live within a minute."
• Never write "simply" or "just".

Screenshots and media

• Add a screenshot when words alone are ambiguous — not for every step.
• Highlight one thing per image, in the house style: [2px red box].
• Crop to what matters; no full-desktop captures.
• Every image needs alt text that says what to look for, not "screenshot".
• Redact real customer data, tokens, and emails.
• Screenshots date fast: note the UI version and re-shoot when the UI changes. Keep any video under [2 minutes] and caption it.

Words and conventions

Keep a running term list so the whole KB says the same thing the same way.

• Numbers: spell out one to nine; numerals for 10 and up.
• Format UI labels in bold, typed input in code, and keys as Ctrl + S.
• Expand an acronym on first use: "single sign-on (SSO)".
• Write dates as [2026-07-10] or "10 July 2026" — never "07/10".

Accessibility and readability

• Reading level at or below the target [Grade 7–9] (run it through a checker)
• Links describe their destination — "see the billing guide", never "click here"
• Every image has meaningful alt text
• Instructions don't rely on colour, shape, or position alone ("the red button on the right" → name it)
• Headings use real heading styles (H2/H3), not bold text, so screen readers can navigate
• Tables hold data, not layout

Metadata every article carries

• Owner — a named person or team who can verify it's correct
• Last reviewed date, distinct from last edited
• Review cadence — [6 months] for pricing / policy / security, [12 months] for stable how-tos
• Type (from the table above) and the contact driver it maps to
• Audience marked public or internal — and the two never contradict each other

Pre-publish checklist (the gate)

Nothing goes live until every box is ticked.

• Title is a task or symptom in the customer's words
• First sentence answers the question — no throat-clearing
• One article type, followed cleanly
• Steps start with verbs, one action each, ending in a success check
• The top failure case is written down, not left to a ticket
• Reading level at or below target; read it out loud once
• Terms match the house list; UI labels bolded correctly
• Every link works and every image has alt text
• No "simply", "just", "obviously", or "easy"
• Owner, last-reviewed date, and review cadence are set
• Searched your top 3 phrases for this topic — this article shows up in the first few results

The point of a style guide isn't to make writers sound identical for its own sake. It's that a customer in a hurry shouldn't have to relearn how your help center works on every article. Same shape, same voice, same words — so the only variable is their problem.