---
title: "Writing Style Guide for Knowledge Base Content"
sidebarTitle: "Writing Style"
description: "The complete style guide for KB contributors: voice, tone, tense, capitalization, punctuation, numbers, formatting, and inclusive language rules."
---
> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.
This style guide defines how every piece of content in the knowledge base should read and feel. Following a shared style isn't about being prescriptive — it's about reducing friction for readers who consume dozens of articles across multiple teams. When voice, tense, and formatting are consistent, readers spend their cognitive energy understanding the content rather than adapting to a new writing style on every page. Treat this guide as your primary reference before you write and your checklist before you publish.
## Voice and Tone
Write in **second person** ("you") throughout every article. Address the reader directly and assume they are the person performing the task or seeking the information.
- **Active voice** keeps sentences clear and direct. Put the actor first: "You configure the integration in the Settings panel" rather than "The integration is configured in the Settings panel."
- **Friendly but professional** — write the way a knowledgeable colleague would explain something in a one-on-one conversation. Avoid stiff, corporate language ("please be advised that") and overly casual language ("super easy, just do this real quick").
- **Explain jargon on first use.** If a term is domain-specific or internal, define it in parentheses or link to a glossary entry the first time it appears in an article. Don't assume the reader already knows it.
## Tense
Use **present tense** when describing how something works, what a feature does, or what the system shows:
> "The dashboard displays all flagged articles in a single view."
Use **imperative mood** (a direct command) for step-by-step instructions. Start the sentence with a verb:
> "Click **Save** to apply your changes."
> "Navigate to **Settings → Integrations** and select the connector you want to configure."
Avoid future tense ("you will see a confirmation message") unless you are genuinely describing something that happens at a later point in a workflow and present tense would be confusing.
## Capitalization
| Context | Rule | Example |
|---|---|---|
| Article headings | Sentence case | "How to configure your workspace" |
| Product and feature names | Title Case (treat as proper nouns) | "the Governance Dashboard", "the Content Audit tool" |
| UI labels | Match exactly what appears in the interface | Click **Save Draft** |
| Job titles | Lowercase unless part of a name | "ask your content manager" vs. "contact Content Manager Priya Nair" |
| Acronyms | All caps; spell out on first use | "knowledge base (KB)" |
Never use ALL CAPS for emphasis in body text. Use **bold** instead.
## Punctuation
**Oxford comma** — always use it in lists of three or more items: "Clarity, consistency, and accuracy."
**End punctuation in lists:**
- If a list item is a complete sentence, end it with a period.
- If a list item is a fragment or short phrase, omit the period.
- Be consistent within a single list — don't mix sentence-style and fragment-style items.
**Em dashes** — use an em dash (—) without spaces on either side to set off a clause. Do not substitute a double hyphen (--).
**Colons** — introduce a list or an explanation. The text before a colon should be a complete clause. Lowercase the first word after a colon unless it's a proper noun or the colon introduces a full independent sentence quoted as a block.
**Avoid exclamation marks** in instructional content. Reserve them for genuinely celebratory moments (e.g., onboarding success screens), and use no more than one per article.
## Numbers
| Situation | Rule | Example |
|---|---|---|
| One through nine | Spell out | "three required fields" |
| 10 and above | Use numerals | "15 articles flagged for review" |
| Steps and numbered procedures | Always use numerals | "Step 3: Review the output" |
| Measurements and quantities | Always use numerals | "2 GB of storage", "30-day review cycle" |
| Starting a sentence | Spell out or rewrite to avoid | "Fifteen articles…" or "There are 15 articles…" |
| Percentages | Use numerals with the % symbol | "87% of flagged articles" |
## Do vs. Don't Examples
Use these patterns as models for clear, consistent KB writing.
1. **Direct, second-person instructions**
> "Navigate to **Settings → Team Members** and click **Invite**."
2. **Active voice with clear subject**
> "The system sends a confirmation email within two minutes."
3. **Sentence-case heading**
> "How to archive outdated content"
4. **Jargon defined on first use**
> "Each article requires a designated content owner — the team member responsible for keeping it accurate and up to date."
5. **Parallel list structure**
> "A good KB article is clear, consistent, and accurate."
Avoid these patterns — they reduce clarity and break consistency.
1. **Passive voice that hides the actor**
> ~~"The confirmation email will be sent after the form is submitted."~~
2. **First person in instructional content**
> ~~"I recommend checking the review date before publishing."~~
3. **Title Case headings**
> ~~"How To Archive Outdated Content"~~
4. **Unexplained jargon**
> ~~"Make sure the CNAME is propagated before you whitelist the origin."~~ *(without any definition or link)*
5. **Inconsistent list punctuation**
> ~~"- Clear content. - Consistent formatting - Accurate facts."~~
## Formatting Conventions
**Bold** — use bold for:
- UI labels and button names (exactly as they appear in the interface)
- Key terms on first use, when the term itself is the subject of the sentence
- Critical information inside a callout or warning
**Inline code** — use `code formatting` for:
- Command-line commands and arguments
- Filenames and file paths
- Environment variables and configuration keys
- Any string the reader must type exactly as written
**Italics** — use italics sparingly and only for:
- Titles of external documents, books, or publications
- Introducing a new technical term in a definition context (as an alternative to bold)
- Do not use italics for emphasis — use bold instead
**Fenced code blocks** — always include a language identifier:
```bash
kb-cli audit --filter stale --since 90d
```
```json
{
"owner": "priya.nair@company.com",
"review_cycle_days": 180
}
```
Never use a plain ` ``` ` block without a language tag. If no specific language applies, use `text`.
## Inclusive Language
Writing for a diverse audience means being deliberate about word choice. Apply these principles to every article.
- **Person-first language** — describe what someone does or needs, not a characteristic that defines them. Write "users who need screen reader support" rather than "blind users."
- **Avoid assumptions about technical skill.** Don't write "simply" or "just" before an instruction — what's simple to you may not be simple to the reader. Replace "just click Save" with "click **Save**."
- **Use gender-neutral language.** Write "they" as a singular pronoun rather than "he or she." Rewrite sentences to be plural when singular phrasing feels forced.
- **Avoid idioms and colloquialisms** that may not translate across cultures or first languages: "out of the box," "circle back," "boil the ocean." Replace them with plain descriptions of what you mean.
- **Don't use ableist metaphors** ("blind spot," "falls on deaf ears") when plain alternatives exist ("gap in coverage," "goes unnoticed").
The goal of inclusive language isn't to police word choice — it's to ensure that every reader feels addressed and capable. When in doubt, choose the plainest, most direct option.
## Frequently Asked Questions
Use first person sparingly and only in specific contexts:
- **"We"** is acceptable when speaking on behalf of the organization in a policy context: "We review all submitted articles within five business days." However, prefer second-person framing when possible: "Your submission will be reviewed within five business days."
- **"I"** is almost never appropriate in KB articles. It introduces a personal perspective that may not reflect team consensus and becomes confusing when content is updated by a different author. The only exception is attributed testimonials or case studies, which are explicitly framed as a single person's account.
- **FAQ responses** may occasionally use "you can" or "we recommend" but should default to imperative mood for any instructional content within the answer.
Internal documentation should be **professional but conversational** — think of it as the tone you'd use in a well-written Slack message to a colleague you respect but don't know well. You don't need to write in full formal register ("It is advisable that contributors ensure…"), but you also shouldn't write the way you'd text a friend ("ok so basically just do this lol").
A practical test: read your draft aloud. If it sounds stiff or robotic, simplify it. If it sounds too casual or vague, tighten it up. The goal is clarity and respect for the reader's time.
Internal docs can be slightly more relaxed about jargon than external-facing content — you can assume the reader knows what a "sprint" or a "PR" is — but you should still define any term that's specific to your team or department rather than the industry at large.
Target a **Grade 8–10 reading level** for all KB content, internal and external. This doesn't mean dumbing down technical material — it means writing clearly enough that someone encountering the topic for the first time can follow along.
Practical ways to hit this target:
- Keep sentences to 20 words or fewer on average (some longer sentences are fine; balance them with shorter ones).
- Prefer common words over formal synonyms: "use" instead of "utilize," "start" instead of "initiate," "show" instead of "display."
- Break long paragraphs into bullets or steps when you're listing multiple distinct items.
- Use the Hemingway App or a similar readability tool to spot sentences that are hard to parse.
The reading level target applies to the prose itself. Technical content — code samples, configuration values, error messages — is exempt and should be accurate rather than simplified.