When can I use first person (I/we)?

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.

What reading level should I target?

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.

Writing Style Guide for Knowledge Base Content

Q: How formal should internal docs be?

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.

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.

Direct, second-person instructions

"Navigate to Settings → Team Members and click Invite."
Active voice with clear subject

"The system sends a confirmation email within two minutes."
Sentence-case heading

"How to archive outdated content"
Jargon defined on first use

"Each article requires a designated content owner — the team member responsible for keeping it accurate and up to date."
Parallel list structure

"A good KB article is clear, consistent, and accurate."

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:

kb-cli audit --filter stale --since 90d

{
  "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.