How to Write a Knowledge Base Style Guide (That People Follow)
A style guide's job isn't to make writing elegant. It's to remove the hundred small decisions that slow contributors down and produce inconsistency — so that ten people writing articles produce something that reads like one person wrote it, and retrieves predictably.
The failure mode is length. A forty-page guide gets skimmed once and ignored. Aim for something a new contributor can absorb in ten minutes.
What belongs in it
Article shape
The highest-value section. Specify the standard structure: a one-sentence answer at the top, then steps, then edge cases, then related links. Consistency here matters more than any wording rule, because it determines whether a retrieved passage stands on its own.
Titling rules
Titles should use the customer's phrasing, not internal terminology. Give three or four before-and-after examples — “Subscription Lifecycle Management” becomes “How to cancel your subscription.” Examples teach this faster than rules do.
Voice and person
Pick second person and active voice, and say so once. “Click Save” rather than “The Save button should be clicked.” This is a short section; long discussions of tone rarely change what people write.
Formatting conventions
- Bold for interface labels; never for emphasis.
- Numbered lists for sequences, bullets for unordered sets.
- Code formatting for anything typed literally.
- Headings that describe content, not clever labels.
Retrieval rules
The section most style guides lack, and the one that matters most if content feeds an AI agent: keep sections self-contained, avoid pronouns that reach across headings, state conditions and numbers explicitly, and never put a critical fact only in an image.
Comma rules, capitalization debates, and anything a contributor would have gotten right by instinct. Every rule you add costs attention; spend it on the ones that change retrieval or comprehension.
Making it stick
- Provide a template, not just rules. Most people follow structure they're handed and ignore structure they have to construct.
- Give three model articles that exemplify the guide. Contributors imitate examples far more readily than they apply principles.
- Review the first article from each new contributor personally. One round of specific feedback beats any amount of documentation.
- Keep it in the authoring flow — linked where people write, not filed in a separate wiki.
“A style guide nobody reads is a template nobody was given. Hand people the shape and most of the rules enforce themselves.”— Knowledge Agents
Reviewing it
Revisit the guide when you notice the same correction being made repeatedly in review — that's a missing rule. And remove rules nobody has needed to enforce in a year; they're costing attention without earning it.
For the broader structure your articles live in, see how to build a customer service knowledge base.
Frequently asked questions
Short enough to absorb in about ten minutes. Long guides get skimmed once and ignored, so prioritize article shape, titling, and retrieval rules over comprehensive grammar coverage.
The standard article shape — a self-contained one-sentence answer first, then steps, edge cases, and related links. It drives both readability and whether a retrieved passage makes sense on its own.
