kb-authoring

Article Anatomy

Mandatory Components

Every knowledge base article includes:

1. Title: Outcome-oriented or symptom-oriented. Written in the language a customer would type into a search bar -- never internal jargon.
2. Summary: 1-2 plain-language sentences stating what the article covers and who benefits from it.
3. Content body: Organized by article type (see below).
4. Cross-references: Links to companion articles for adjacent topics.
5. Metadata: Category, tags, intended audience, last-modified date.

Formatting Standards

• Headings (H2, H3): Create a scannable outline so readers can jump to the relevant section.
• Numbered lists: For ordered procedures where sequence matters.
• Bullet lists: For unordered sets of items or options.
• Bold text: For UI labels, critical terms, and points of emphasis.
• Code blocks: For commands, API payloads, error strings, and configuration snippets.