Knowledge base style guide: template and examples

A knowledge base style guide defines how contributors write and present help content: the terminology they use, how they organize instructions, how they identify interface controls, and how they explain information through text and images. It gives writers and reviewers a shared basis for recurring editorial decisions.

Start with the decisions your team repeatedly debates, choose clear defaults, and demonstrate them with examples. You do not need to recreate a grammar manual. The starter guide below provides an adaptable set of rules, followed by examples showing how to apply them without changing the underlying facts.

Define the scope before writing the rules

Record who the articles serve, which tasks they support, what readers already know, and which content types the guide covers. Customer instructions may need explanations that agent-only procedures can omit, while internal documentation may require role-specific terminology. Do not assume that an internal audience shares the same expertise.

Keep related documents distinct. A style guide addresses recurring language and presentation choices. An article template supplies a structure for a particular task. A content standard may also cover required information and metadata. Governance assigns responsibility and authority. Organizations use these labels differently; define their meaning within your own documentation.

Choose a reference for questions your local guide does not answer. KnowledgeOwl recommends using an existing style guide and documenting additions or exceptions as an alternative to starting from scratch. Google’s documentation style guide similarly explains a reference hierarchy that starts with project-specific guidance.

For editorial questions, use your approved house rules first, then the selected reference. Product facts, exact interface labels, and applicable accessibility requirements are separate constraints—not preferences that an editor can override for consistency. When an unresolved choice affects meaning, ask the appropriate subject-matter reviewer rather than silently standardizing it.

A starter knowledge base style guide you can adapt

This knowledge base style guide template is a proposed policy for an English-language software help center. It is not an official standard or a description of a real organization. Its complete default rules can serve as a starting point; the sections that follow explain the decisions and exceptions.

Scope: Customer-facing how-to, troubleshooting, reference, and short-answer articles. Language: American English. Owner: The documentation lead maintains editorial rules; subject-matter reviewers validate product behavior. Reference: Use the Google developer documentation style guide for editorial questions not addressed here.

Writing and organization defaults

AreaDefault rule
Voice and toneAddress the reader as “you” where useful. Be direct, calm, and respectful. Avoid blame, promotional claims, and language that minimizes difficulty.
TerminologyUse the approved term for each concept. Preserve exact product names, interface labels, error messages, and identifiers. Flag conflicting terminology for review.
Titles and headingsUse sentence case, retaining proper names and exact labels. Identify the task, symptom, or subject. Use actual heading levels to express the document’s structure.
Opening informationGive the answer or purpose first. State audience, permissions, prerequisites, and version limits when they affect applicability.
Article structureChoose a pattern that fits the reader’s task. Do not require procedural steps, a cause, or an FAQ when they add no useful information.
InstructionsNumber actions when sequence matters. Give the necessary starting location, distinguish optional actions, and explain how to recognize the expected result.

Presentation and review defaults

AreaDefault rule
Interface and technical textBold interface labels when referring to controls. Use code formatting for literal filenames, identifiers, and commands. Explain replaceable values separately.
Warnings and notesPut consequential warnings before the risky action. Keep required instructions in the main flow. Use optional notes and tips only when they add distinct value.
Links and tablesDescribe link destinations. Identify relevant access restrictions or file types. Use tables for genuine relationships or comparisons, with meaningful headers.
Screenshots and mediaAdd visuals only when they clarify the task. Keep essential instructions selectable as text. Preserve captured states and disclose composites or illustrative recreations.
Text alternativesChoose image alternatives according to purpose and context. Provide accessible equivalents for essential visual or audio information.
Review and exceptionsCheck editorial consistency, factual accuracy, and accessibility separately. Record an approved exception’s reason and scope; do not treat it as a silent change to the guide.

These defaults intentionally leave room for judgment. A useful guide explains the decision an editor should make—not only the appearance the finished page should have.

Match the article pattern to the reader’s task

Use a consistent style without forcing every article into the same structure. GitLab’s knowledge base style guide, for example, distinguishes titles for break/fix issues, how-to tasks, and questions. The practical lesson is to identify the reader’s need before choosing headings.

GitLab knowledge base style guide showing title recommendations and examples for troubleshooting, how-to, and question-and-answer articles.
Article typeUseful starting patternAvoid forcing
How-toPurpose and applicability, prerequisites, ordered actions, expected result.A troubleshooting section when there is no relevant failure to explain.
TroubleshootingObservable symptom, affected environment, diagnostic checks, resolution or workaround, escalation.An invented cause when the evidence supports only a symptom or hypothesis.
Reference or explanationDirect definition or overview, organized details, limits, examples where useful.Artificial numbered steps for information that has no sequence.
Short answerThe actual question, a direct answer, and necessary conditions or exceptions.A long introduction or several empty template sections.

Use meaningful titles and real heading elements. W3C’s writing accessibility guidance explains that page titles should distinguish content and that semantic headings communicate structure. Making a paragraph larger or bold does not replace a heading.

Example 1: replace a category label with a task title

Illustrative task: The article explains how users change their own display name.

Before: Profile settings

After: Change your display name

The revised title identifies the task without claiming to cover every profile option. Add a product or version qualifier only when it helps distinguish the article from another answer. Do not turn the title into a list of keyword variations.

Keep the voice consistent and the terminology precise

Define voice as the qualities that remain steady: helpful, direct, and respectful. Let tone reflect the situation. Routine setup can sound conversational; a warning about a permanent action should be restrained and specific. Neither needs promotional language.

Google’s voice and tone guidance favors approachable language without slang, unnecessary formality, or culturally specific references. Apply that principle by choosing familiar words where they preserve meaning and explaining necessary technical terms.

Example 2: remove judgment without removing the instruction

Before: Obviously, you need to select a workspace before you can view its activity log.

After: Select a workspace to view its activity log.

The requirement remains unchanged. The revision removes a judgment about how easy the task should be. Use the same test for “just” and “simply”: remove them when they add no operational information.

Prefer active constructions when the reader needs to know who acts. Do not ban passive voice when the actor is unknown or irrelevant. Review sentence length according to comprehension, not a universal ceiling. In this starter guide, readability scores are prompts for inspection—not publication gates or evidence that instructions are correct.

Example 3: distinguish similar-looking actions

Fictional product facts: In this example, Archive removes a report from the active list but retains it. Delete permanently removes it. These definitions illustrate a terminology decision; they are not claims about a real product.

Before: Delete the report with Archive to keep it out of your active list.

After: Select Archive to remove the report from your active list without deleting it.

The revision resolves conflicting language using the supplied facts. Record each approved term, its meaning, discouraged substitutes, and any exact interface-label exception. Do not vary technical terms merely to avoid repetition. If the product facts are unknown, ask for clarification instead of guessing which verb is correct.

Use American English in prose while preserving literal values. For dates, adopt an unambiguous form such as “January 14, 2027”; retain a different format when the documented input requires it. Specify a time zone when timing affects the task. Google’s date and time guidance distinguishes prose conventions from formats required by an interface or code.

Write procedures readers can follow and verify

Use numbered steps when order matters, bullets for unordered items, and a sentence for a straightforward single action. Microsoft’s procedure guidance allows related short actions in the same interface location to be combined. The goal is a meaningful action or action group—not a separate step for every click.

State necessary permissions and conditions before the reader begins. Identify the application, page, or dialog when the starting location could be ambiguous. Label optional actions and separate substantial branches rather than hiding several different procedures inside one step.

Google documentation style guide comparing recommended and not recommended instructions for identifying where to complete a task.

Google’s procedure guidance also emphasizes context, purpose, and useful results. End with an observable outcome, and explain the next action when the expected result does not occur. “Done” does not tell the reader what succeeded.

Choose conventions for controls and literal text

In this guide’s proposed convention, bold visible or accessible user interface (UI) labels, such as Save. Preserve the label’s wording and capitalization. Rutgers IT’s guide provides an institutional example of bold UI labels and input-neutral instructions. Use “select” where appropriate, but name a specific interaction when the task requires one.

Do not identify a control only by color or position. Use a genuine menu path, such as Settings > Notifications, only when it represents that navigation. Describe field entry and confirmation actions separately rather than squeezing them into a misleading chain.

Use code formatting for literal filenames, identifiers, and commands. State what readers must replace, and distinguish placeholder text from a value they should enter unchanged. Keep exact error messages selectable as text. Preserve case-sensitive spelling, straight quotes, and punctuation in executable material.

For keyboard instructions, choose a consistent notation, such as Ctrl+S for a simultaneous shortcut, and identify the relevant platform when necessary. Test real shortcuts and commands rather than assuming that formatting consistency makes them valid.

Example 4: turn a crowded instruction into a short procedure

Fictional scenario: Workspace owners can change a weekly summary’s delivery day. The controls and confirmation below belong to an illustrative interface, not a real product.

Before: Owners can change the weekly summary to Tuesday by going to workspace Settings and then Notifications, choosing Tuesday from Day, and pressing Save, after which “Preferences saved” appears; ask the workspace owner if you do not have access.

After: You need the workspace owner role to change the weekly summary day. If you do not have access, ask the workspace owner.

  1. In your workspace, go to Settings > Notifications.
  2. In Day, select Tuesday.
  3. Select Save. The confirmation “Preferences saved” appears.

The revision preserves the role requirement, controls, chosen value, and expected result. It changes the organization, not the product behavior. That is the standard to apply when editing a real procedure.

Use warnings, links, and tables deliberately

For the starter guide, treat a prerequisite as something needed before beginning, a note as useful context, a tip as an optional improvement, and a warning as notice of a consequential risk. These labels are editorial conventions, not universal classifications.

Put critical information before the affected action and keep it in the reader’s path. Google’s notice guidance cautions against overusing notices because they lose visual distinctiveness. Do not turn every qualification into a callout or hide required steps inside optional-looking tips.

Example 5: move the consequence before the action

Fictional context: This example uses the permanent report-deletion behavior defined earlier.

Before: Select Delete. Deletion is permanent, so cancel if you still need the report.

After: Deleting this report is permanent. If you still need it, cancel. Otherwise, select Delete.

The warning now arrives before the decision. No recovery method or additional product capability has been invented.

For links, describe the destination or action rather than using “click here.” Include relevant access restrictions or file types. These practices are covered in W3C’s link-text guidance. For this starter guide, links open in the same tab by default; an exception needs a user-centered reason and notice when the behavior is unexpected.

W3C accessibility guidance comparing vague link text with meaningful link wording that describes the destination.

Use a table when readers need to compare related values or consult structured information. W3C’s tables tutorial explains that header and data relationships need appropriate markup. Keep headers meaningful and tables compact; split a complicated comparison rather than using tiny text or a screenshot of the table.

Set screenshot and accessibility rules

Add a screenshot when it explains a location, state, or visual relationship that the text cannot communicate efficiently. Do not illustrate every obvious button press. Google’s image guidance recommends relevant crops and real text instead of images of code, terminal output, or other text.

Keep essential instructions in the article, then crop the capture to retain the necessary context. Check label readability at the intended display size, including on a narrow screen. Choose dimensions and format for the content; a fixed landscape ratio is not suitable for every menu or dialog.

Adopt a provenance rule: preserve captured text, values, and interface states. Label an annotated capture as annotated, a combination of captures as a composite, and a mockup as illustrative. Credit captures taken from public documentation. An image recreated with generative tools must not be presented as evidence of an actual interface session.

Prefer approved sample data. When personal information must be obscured, Google’s screenshot guidance specifies fully opaque covering rather than blur and flattening exports that can contain layers. Inspect the final export before publication; do not assume the working file and published image are identical.

Choose text alternatives by purpose

Use W3C’s alt-text decision tree to decide what an image contributes in context. An informative image needs its relevant information conveyed. An image serving as a control needs its function conveyed. A purely decorative or appropriately redundant image can use an empty alt="" attribute; simply omitting the attribute is not the same decision.

Excerpt from W3C's alt decision tree explaining text alternatives for informative, complex, and redundant images.

For an illustrative screenshot of the weekly-summary setting, an appropriate description might be: “Notifications settings with Tuesday selected as the weekly summary day.” Whether that description is needed depends on what the surrounding text already conveys and whether the image adds information.

Use a caption for visible context, attribution, or disclosure such as “Two screenshots combined to show the complete settings panel.” A complex diagram may need a fuller explanation nearby. Alt text is not a place to repeat keywords or reproduce the entire article.

For media, plan captions for instructional video, transcripts for audio, and descriptions of important visual information not conveyed by the soundtrack. W3C’s media guidance explains how the necessary alternatives depend on the content. These writing checks support accessibility; they are not a complete assessment of the website or publishing platform.

Apply the guide with separate review checks

Test the guide on representative articles before making it a broad requirement. Ask two contributors to revise the same short passage, then compare their decisions. If both interpretations fit the rule but produce conflicting results, clarify the rule or add an exception example.

Keep editorial conformance separate from technical verification. The Consortium for Service Innovation states that the KCS v6 Content Standard Checklist is not a technical accuracy review. Consistent terminology and formatting cannot establish whether a procedure works.

  • Editorial check: Can the reviewer explain the title, structure, terminology, and formatting choices using the guide? Are exceptions documented?
  • Technical check: Has a qualified reviewer verified the applicable behavior, permissions, prerequisites, labels, and outcomes against an approved source or safe test?
  • Accessibility check: Are headings, links, tables, media alternatives, and instructions meaningful in the published page rather than merely attractive in the editor?

Use automated checks as flags for investigation, not substitutes for these decisions. An approved-term check can identify a possible inconsistency, but a reviewer must determine whether the text is an exact interface label or a legitimate exception. Likewise, an image having an alt attribute does not establish that the alternative is useful.

For AI-assisted editing, require a comparison with the original and the approved facts. Check especially for changed permissions, lost conditions, weakened warnings, altered commands, or invented outcomes. Accept a revision because it preserves meaning and improves usability—not because it sounds smoother.

Maintain a small, visible decision record

Give the guide an accountable owner and a simple change-request route. Record the proposed rule, reason, example, decision, and affected content. For an exception, state where it applies and why; an exact product label may justify a capitalization exception without changing every heading.

Revisit rules when terminology, interfaces, accessibility needs, or recurring editorial disagreements change. Update representative examples and tell contributors what changed. Prioritize corrections that affect meaning or task completion before cosmetic cleanup across the archive.

A useful style guide makes the next writing decision easier. Keep the core rules short enough to consult, support difficult choices with examples, and verify that consistency serves the reader rather than becoming an end in itself.

Sources verified: November 5, 2026.