vamseeachanta Universal Article Elements (+1)
Universal Article Elements
Every KB article should include:
- Title: Clear, searchable, describes the outcome or problem (not internal jargon)
- Overview: 1-2 sentences explaining what this article covers and who it's for
- Body: Structured content appropriate to the article type
- Related articles: Links to relevant companion content
- Metadata: Category, tags, audience, last updated date
Formatting Rules
- Use headers (H2, H3) to break content into scannable sections
- Use numbered lists for sequential steps
- Use bullet lists for non-sequential items
- Use bold for UI element names, key terms, and emphasis
- Use code blocks for commands, API calls, error messages, and configuration values
- Use tables for comparisons, options, or reference data
- Use callouts/notes for warnings, tips, and important caveats
- Keep paragraphs short -- 2-4 sentences max
- One idea per section -- if a section covers two topics, split it