Skip to main content

Style Guide

Authoring standards for contributors writing or reviewing documentation for the Knowledge Management Graph.

Audience: Contributors — human developers and AI documentation agents. Version: 0.1.0-beta Last Updated: 2026-03-03

Before writing documentation, read this guide. Every rule includes a citation showing where the standard comes from.

Contents​

  1. Non-Negotiables
  2. Voice and Tone
  3. Canonical Terminology
  4. Page Patterns
  5. Accessibility
  6. Formatting Standards
  7. Links and Cross-References
  8. Citations and Best-Practice Traceability
  9. Pre-Commit Checklist
  10. Related Documentation

Citation Keys​

The following authoritative sources are referenced throughout this guide using [CitationKey] notation.

KeySourcePrinciple
[Nielsen2015]Nielsen Norman Group, "Plain Language Is for Everyone, Even Experts" (2015)Plain language reduces cognitive load; read time decreases 58%
[GoogleDevDocs]Google Developer Documentation Style Guide (2024)Readers scan, not read linearly; hierarchy and information density matter
[MicrosoftMSTP]Microsoft Manual of Style, 4th ed.Task-based organization improves findability; use active voice and imperative mood
[508CFR1194]36 CFR Part 1194, Section 508 StandardsAccessible technology requirements for documentation
[WCAG21]WCAG 2.1, Level AA (W3C, 2018)Web Content Accessibility Guidelines
[MadeToStick]Heath & Heath, "Made to Stick" (2007)Concrete examples are 40% more memorable than abstract descriptions
[DiataxisFramework]Divio Documentation System ("Diataxis"), Procida (2021)Four documentation types: tutorials, how-tos, explanations, references
[WritersGuide]The Chicago Manual of Style, 17th ed.Comma usage, capitalization, heading case conventions
[gitbook-style-guide]gitbook-docs/docs-maintenance/documentation-style-guide.mdProject-specific platform language and page patterns

1. Non-Negotiables​

These rules cannot be overridden without an explicit versioned decision (ADR). Every contributor must follow them on every document.

1.1 Third-person voice in comprehensive documentation​

Apply to: CONCEPTS.md, COMMAND-GUIDE.md, GETTING-STARTED.md, NAVIGATION-INDEX.md.

  • ✅ "The system extracts metadata automatically."
  • ✅ "The command creates a lesson file in the active category."
  • ❌ "You can see that the system extracts..."
  • ❌ "We recommend running this command first."

Validation: grep -iE "\b(you|your|we|our|they|them)\b" [file]

Citation: [gitbook-style-guide] Non-negotiable #1; [MicrosoftMSTP] Sec. 3.2 — third-person for reference documentation.

1.2 Imperative or neutral voice in quick-reference documentation​

Apply to: CHEAT-SHEET.md.

  • ✅ "Run /kmgraph:init to initialize."
  • ✅ "This command initializes the knowledge graph."
  • ❌ Mix of imperative and third-person within the same document.

Citation: [MicrosoftMSTP] Sec. 3.4 — imperative mood for task instructions.

1.3 Platform-agnostic language unless describing Claude Code–specific behavior​

  • ✅ "The lesson template supports any LLM workflow."
  • ✅ "MCP-compatible tools can extend the plugin."
  • ✅ "Claude Code users can invoke commands via the / prefix."
  • ❌ "Claude will extract the metadata." (when the feature is not Claude Code–specific)

Citation: [gitbook-style-guide] Platform Language section.

1.4 Command prompt text is immutable​

Never paraphrase or summarize code blocks in /commands/. Command prompt text must be reproduced verbatim; any modification is treated as a versioned decision requiring an ADR.

Citation: [gitbook-style-guide] Non-negotiable #5; immutability protects LLM reproducibility.

1.5 Never modify /commands/ or core/templates/ without explicit permission​

These directories contain LLM execution prompts and structured parsing templates. Changes break functionality.

  • If a change appears necessary: stop and ask the project maintainer first.
  • Allowed: adding new files in these directories when explicitly authorized.
  • Never allowed: editing existing command or template files without maintainer sign-off.

Citation: MEMORY.md Code Protection Rules; [GoogleDevDocs] "Separate concerns between authoring and execution."

1.6 No hardcoded counts of mutable collections​

Never write specific counts for collections that grow between releases.

Apply to any reference to commands/, skills/, agents/, hooks/, core/templates/, mcp-server/src/tools/, or any directory whose contents change between releases.

DisallowedAllowed
"26 slash commands""Every slash command", "All slash commands"
"10 skills""Each auto-triggered skill", "All skills"
"8 subagents""Every subagent", "The agent catalog"
"13+ templates""All bundled templates", "The template library"
"5 lifecycle events""Each lifecycle event", "The lifecycle hooks"

Why: A specific number means every release that adds or removes an item also requires a documentation edit. Missed edits become silent inaccuracies that erode trust.

Validation grep (see §9 Pre-Commit Checklist):

grep -nE '\b[0-9]+\s+(commands?|skills?|agents?|hooks?|templates?|tools?|subagents?|events?)\b' docs/

Any match in user-facing docs is a style violation. Allowed exceptions: line counts, phase counts, version numbers.

Citation: [GoogleDevDocs] "Avoid information that quickly becomes stale"; [gitbook-style-guide] (ADR-027, 2026-04-08).

2. Voice and Tone​

2.1 Voice by document type​

Choose the correct voice for each document type. Mixing voices within a document is not permitted.

DocumentVoiceExample
CONCEPTS.mdThird-person"The system captures git metadata automatically."
COMMAND-GUIDE.mdThird-person"The command creates a lesson file in the active category."
GETTING-STARTED.mdThird-person"The initialization wizard prompts for project name."
NAVIGATION-INDEX.mdThird-person"The index organizes documentation into four access paths."
CHEAT-SHEET.mdImperative or neutral"Run /kmgraph:init." or "This command initializes..."
STYLE-GUIDE.md (this document)Imperative"Use third-person voice."
Code comments and examplesAny styleException to all voice rules.

Citation: [GoogleDevDocs] "Match the voice to the document's purpose."

2.2 Tone principles​

Lead every section with an outcome — state what the reader gains, not what the section contains.

  • ✅ "This section defines heading rules so contributors produce consistent hierarchy across all docs."
  • ❌ "This section is about heading rules."

Prefer concrete nouns over pronouns:

  • ✅ "The command writes to lessons-learned/."
  • ❌ "It writes to the folder."

Additional tone rules:

  • Short paragraphs (4 lines or fewer)
  • Short lists (7 items or fewer before splitting into subsections)
  • Avoid implementation detail in introductory content; reserve it for Advanced sections
  • Every technical claim must be demonstrable with an example

Citations: [GoogleDevDocs] "State the purpose before the details."; [Nielsen2015] plain language reduces read time 58%; [MicrosoftMSTP] "Use short sentences and paragraphs."

3. Canonical Terminology​

Use the terms in the "Use This Term" column consistently across all documentation. Using alternative terms creates confusion and undermines searchability.

Use This TermNever UseDefinition
Commandslash command, plugin command, skillA prompt manually invoked by the contributor via /kmgraph:…
Skillcommand (for autonomous triggers)A prompt triggered automatically by the AI
Templateform, blank, scaffoldA pre-formatted markdown file providing structure
Knowledge graphKG (in contributor-facing prose), database, notes systemThe quick-reference layer of organized documentation
KGkg, K.G.Acceptable abbreviation in code and technical contexts only
Lesson Learnedlesson, note, entryA structured problem-solving document in lessons-learned/
ADRdecision record, architecture noteArchitecture Decision Record, numbered sequentially
MEMORY.mdmemory file, context fileThe AI long-term context file at the KG root
Claude CodeClaude, the assistantWhen referring to the Claude Code IDE plugin specifically
Any LLMClaude, the AIWhen describing platform-agnostic workflows
MCPplugin API, toolModel Context Protocol integration
GitHub Issueissue (alone)Platform-level bug report or feature request on GitHub
[AUTO]automatic, auto-filledField filled by the command without contributor input
[MANUAL]manual, user-filledField requiring contributor input
ISO 8601date formatYYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ

Citation: [gitbook-style-guide] Terminology section; [GoogleDevDocs] "Use a word list to enforce consistency."

4. Page Patterns​

Apply the correct structural pattern for each document type. Predictable structure improves scannability and reduces the cognitive load of finding information. [GoogleDevDocs]

4a. Guide page pattern​

Apply to: GETTING-STARTED.md, CONFIGURATION.md, WORKFLOWS.md, and similar task-oriented guides.

# [Title]

[One-sentence description of what this guide covers and who it is for.]

---

## [What It Is] (optional — omit if obvious from title)
## [When to Use / Choose a Path]
## [Step-by-step content sections]
## Troubleshooting
## Related Documentation

Citation: [gitbook-style-guide] Guide Page pattern; [DiataxisFramework] How-to guide structure.

4b. Command page pattern​

Apply to: individual command entries in COMMAND-GUIDE.md.

### 🟢 `/kmgraph:[command-name]`

**Purpose**: [One-line description]

**When to use**:
- [Scenario 1]
- [Scenario 2]

**What it does**:
1. [Step 1]
2. [Step 2]

**Time**: [Estimate]

**Example**:
```bash
/kmgraph:[command-name] [optional-args]

Tips (optional):

  • [Tip]

Difficulty badges: 🟢 Essential / 🟡 Intermediate / 🔴 Advanced.

**Citation**: `[gitbook-style-guide]` Command Page pattern; `[MicrosoftMSTP]` "Give examples for every major operation."

---

### 4c. Concept entry pattern

Apply to: term definitions in `CONCEPTS.md`.

```markdown
### [Term]

**What it is**: [Plain-English definition, 1–2 sentences]

**Why it matters**: [Why a contributor needs to know this]

**Example**: [Concrete example — never abstract]

**Plain English**: [One-sentence analogy]

Citation: [MadeToStick] — concrete examples are 40% more memorable; [DiataxisFramework] explanation document type.

4d. Lesson Learned pattern​

Lessons follow the template in core/templates/lessons-learned/lesson-template.md. Refer contributors to that template. Do not duplicate the structure here.

Citation: [DiataxisFramework] — reference documents describe structure, not process.

4e. ADR pattern​

ADRs follow the template in core/templates/decisions/ADR-template.md. Refer contributors to that template.

Citation: [DiataxisFramework] — reference documents describe structure, not process.

4f. Changelog entry pattern​

Apply to: every version section in CHANGELOG.md.

Each version section opens with a ### TL;DR subsection, followed by the standard Keep a Changelog technical blocks (### Added, ### Changed, ### Removed, ### Fixed).

Required subsection structure​

### TL;DR

:::info[Short plain-English headline describing a user-visible change.]

Brief plain-English explanatory text providing context.

:::
:::info[Short plain-English headline for a workflow that is now automated.]

Brief plain-English explanatory text on what the user no longer needs to do manually.

:::
:::info[Short plain-English headline explicitly flagging a behind-the-scenes change.]

For example: Internal architecture reorganized; no changes from your perspective.

:::

Rules for ### TL;DR​

  • Write for a developer who uses KMGraph daily but is not reading the source code
  • State what is different about daily use, not what code changed internally
  • Explicitly call out workflows that are now automated — what the user no longer needs to do manually
  • Explicitly call out commands whose behavior, name, or invocation changed
  • Explicitly flag changes that are purely behind the scenes — do not omit them; include an info block to confirm nothing changed for the user
  • Use plain English; avoid technical terms that are not already defined in Section 3 of this guide
  • Use MkDocs !!! info "Headline" admonitions rather than plain bullet points
  • Sub-bullets, code blocks, or nested headers are permitted inside the admonition block
  • Each block is a complete thought and stands alone without requiring the reader to check the technical sections below

Placement​

Place ### TL;DR immediately after the ## [version] - date heading, before all technical subsections (### Added, ### Changed, ### Removed, ### Fixed). The user sees the high-level summary first; the technical detail follows for those who need it.

Example​

## [1.0.0] - 2026-04-01

### TL;DR

:::info[Zero-friction MCP setup.]

If the KMGraph MCP server isn't connected, the assistant will now offer to automatically configure it for Gemini CLI, Cursor, Windsurf, Continue.dev, or VS Code. No manual JSON editing required.

:::
:::info[Behind the scenes only:]

The internal search index format changed; search results are unchanged from your perspective.

:::
### Added
- New `kg_capture` MCP write tool

Citation: [Nielsen2015] — plain language reduces cognitive load; changelog readers are users, not implementers. [GoogleDevDocs] — "State the purpose before the details."

5. Accessibility​

All contributor-facing and user-facing documentation must meet Section 508 standards (36 CFR Part 1194) and WCAG 2.1 Level AA.

Apply these rules to every document before committing.

RequirementRuleValidation
Heading hierarchyNever skip levels (H1→H2→H3, never H1→H3)Manual review
Link textAlways descriptive — never "click here", "read more", "here", or "this link"grep -i "click here|read more|\bhere\b|this link"
Table headersEvery table has a header row with |---| separatorVisual check
Image alt textEvery image has descriptive alt text ![description](path)grep -P "!\[\]\(" catches empty alt text
Mermaid diagramsRequire: text description before diagram, text-based alternative for screen readers, WCAG contrast-compliant colorsManual review
Language complexityPlain language preferred; Flesch-Kincaid grade level ≤10 for contributor-facing docsOptional: readable npm package

Citations: [508CFR1194] — 36 CFR Part 1194 Section 508 Standards; [WCAG21] — WCAG 2.1 Level AA; MEMORY.md 508 Accessibility Compliance section.

6. Formatting Standards​

6.1 Headings​

  • Title case for H1 only: # Documentation Style Guide
  • Sentence case for H2–H4: ## Voice and tone, ### When to use imperative
  • No punctuation at the end of headings
  • No more than 4 levels of heading depth in any document
  • Never use a heading solely for visual styling

Citation: [GoogleDevDocs] heading capitalization rules; [WritersGuide] heading case conventions.

6.2 Lists​

  • Unordered lists (-) for items without inherent order
  • Ordered lists (1.) for sequential steps only
  • No more than 2 levels of nesting
  • Each item is a complete thought, ending without punctuation unless it is a full sentence
  • Lists of 8 or more items: break into subsections

Citation: [MicrosoftMSTP] list formatting.

6.3 Code blocks​

  • Always specify the language: ```bash, ```yaml, ```markdown, ```json
  • Command invocations always use bash code blocks
  • Inline code (backticks) for: file names, directory paths, command names, field names, flag names
  • Never wrap multi-line code in inline code

Validation: grep -n '^\``$' [file]` — returns 0 for a clean file.

Citation: [GoogleDevDocs] code formatting.

6.4 Tables​

  • Pipe-based markdown tables with a header separator row
  • Left-aligned columns by default
  • Keep table cells concise (15 words or fewer per cell)
  • Provide a plain-text equivalent for complex tables when screen readers cannot parse them

Citation: [WCAG21] table accessibility; [GoogleDevDocs] table formatting.

6.5 Callout boxes​

Callouts highlight important information. Two formats are supported depending on rendering context:

Format 1: Blockquote Syntax (GitHub-Compatible)​

Use blockquote syntax with a bold label. Works on GitHub and any markdown renderer.

> **Note:** Informational context the reader should know.
> **Tip:** Actionable optimization or shortcut.
> **Warning:** Risk of data loss or a breaking change.
> **Important:** A must-know requirement before proceeding.

When to use: Raw markdown files, GitHub previews, or when maximum compatibility is needed.

Format 2: MkDocs Admonitions (MkDocs-Enhanced)​

Use MkDocs admonition syntax for richer styling on the documentation site.

:::note[Note]

Informational context the reader should know.

:::
:::tip[Pro Tip]

Actionable optimization or shortcut.

:::
:::warning[Common Pitfall]

Risk of data loss or a breaking change.

:::
:::danger[Important]

A must-know requirement before proceeding.

:::
:::info[For Your Information]

Additional context or related resources.

:::

When to use: Comprehensive documentation files (COMMAND-GUIDE.md, CONCEPTS.md, GETTING-STARTED.md) where site rendering matters.

Guidelines​

  • Reserved keywords: Note, Tip, Warning, Important, Info
  • Do not place consecutive callout boxes without prose between them (either format)
  • Use blockquotes for lessons learned and concise guides
  • Use admonitions for main documentation sections and learning paths
  • All callout text must include accompanying text — never rely on formatting alone to convey meaning (WCAG 2.1)

Citation: Google Dev Docs style guide, Material for MkDocs admonition support, WCAG 2.1 1.1.1 Non-text Content.

6.6 Emojis and badges​

  • Difficulty badges (🟢 Essential / 🟡 Intermediate / 🔴 Advanced) are permitted in command documentation only
  • Emojis elsewhere: use only when they carry semantic meaning (✅ complete, ❌ not supported); never for decoration
  • Every emoji must have accompanying text — never rely on an emoji alone to convey meaning

Citation: [WCAG21] 1.1.1 Non-text Content — emojis must not be the sole conveyor of information.

  • Use relative paths: [Command Guide](COMMAND-GUIDE.md), [Pattern Writing Guide](reference/PATTERNS-GUIDE.md)
  • Never use absolute file system paths (/Users/…)
  • Every document must have a "Related Documentation" section linking to at least 2 other documents
  • Cross-references should be bidirectional: if doc A links to doc B, doc B should link back to doc A

Citation: [GoogleDevDocs] cross-reference guidance; MEMORY.md project standards.

  • Use descriptive link text that describes the destination, not the URL
  • ✅ [Google Developer Documentation Style Guide](https://developers.google.com/style)
  • ❌ [https://developers.google.com/style](https://developers.google.com/style)
  • Open in the same tab (default markdown behavior)

Citation: [WCAG21] 2.4.4 Link Purpose.

  • Section IDs are auto-generated from heading text in GitHub-flavored markdown
  • Reference with #heading-text-kebab-case
  • Test all anchor links before committing:
npx markdown-link-check [file]

Citation: [GoogleDevDocs] anchor links.

8. Citations and Best-Practice Traceability​

Every design decision in documentation must include a citation using the [CitationKey] notation defined in the Citation Keys table at the top of this guide.

8.1 When a citation is required​

  • Any structural decision (why this heading order, not another)
  • Any voice or tone rule
  • Any accessibility requirement
  • Any formatting convention that differs from generic markdown defaults

8.2 When a citation is not required​

  • Code examples (these follow the behavior of the actual commands)
  • Factual statements about the project itself (file paths, command names, dates)

8.3 Citation format in plan files​

**Citation**: `[Nielsen2015]` — Plain language reduces cognitive load 50%

8.4 Citation format in the style guide itself​

Include the citation inline at the end of the rule it supports:

> **Best practice**: Lead with outcomes before details. `[GoogleDevDocs]`

Or as a standalone line after the rule block:

**Citation**: `[GoogleDevDocs]` heading capitalization rules; `[WritersGuide]` heading case conventions.

Citation: MEMORY.md Best Practice Citations section.

9. Pre-Commit Checklist​

Run this checklist before marking documentation complete or committing a new or updated document.

Voice​

  • Voice matches document type (third-person or imperative per Section 2)
  • No second-person pronouns in comprehensive docs: grep -iE "\b(you|your|we|our)\b" [file]
  • Concrete nouns used instead of ambiguous pronouns where possible

Terminology​

  • All terms match the Canonical Terminology table (Section 3)
  • "GitHub Issue" used for platform issues, not bare "issue"
  • Platform language correct: "Claude Code" vs "any LLM" vs "MCP"

Structure​

  • Page follows the correct pattern for its document type (Section 4)
  • H1 exists and is unique; headings never skip levels
  • Every section leads with an outcome statement, not a content description

Accessibility​

  • No "click here" or bare-URL link text: grep -i "click here\|read more\|\bhere\b" [file]
  • All tables have header rows
  • All images have non-empty alt text: grep -P "!\[\]\(" [file]
  • Any Mermaid diagram has a text description before it

Formatting​

  • All code blocks have a language specifier: grep -n '^\``$' [file]`
  • File names and path names wrapped in inline code
  • No absolute file system paths in prose: grep "/Users/" [file]
  • H1 in title case; H2–H4 in sentence case
  • All internal links use relative paths
  • "Related Documentation" section present with at least 2 links
  • Broken link check: npx markdown-link-check [file]

Citations​

  • Every structural, voice, or accessibility decision has a [CitationKey]

Authoring references:

Templates:

Contributor workflows:

Created: 2026-02-20 Version: 1.0 Applies to: v0.0.7-alpha and later