Knowledge Base Article Writing

Produce polished help center articles and FAQ entries that deflect support tickets by giving customers clear, self-serve answers. This skill turns support ticket patterns, product changes, and common questions into structured articles optimized for readability, search, and scannability, following documentation best practices for step-by-step guides, troubleshooting flows, and reference material.

Workflow

1. Identify topic from support data — Mine support ticket trends, search analytics (what customers search for but don't find), and CSM feedback to find the highest-impact topics. Prioritize by ticket volume (articles addressing the top 10 question clusters deflect the most tickets), topic complexity (complex topics benefit most from written guides), and recency (new features or recent changes need documentation immediately).

2. Research the solution — Gather the authoritative answer from engineering docs, internal wikis, product specs, and subject matter experts. Test the workflow yourself end-to-end in the product to verify accuracy. Document the exact UI text, button labels, and navigation paths as they appear in the current product version. Note any prerequisites, required permissions, or plan-tier restrictions.

3. Structure the article — Follow a consistent template: Title (action-oriented, matches how customers search), Summary (1-2 sentence answer for scanning), Prerequisites (what the reader needs before starting), Steps (numbered, one action per step, with expected outcome), Troubleshooting (common errors and their fixes), and Related Articles (links to adjacent topics). Keep the hierarchy flat — use H2 for major sections and H3 sparingly.

4. Add visual aids and code examples — Include screenshots for UI-heavy workflows (annotated with numbered callouts matching the steps), code snippets for API or CLI workflows (with language tags, copy buttons, and expected output), and diagrams for architecture or flow explanations. Every image should have alt text. Every code block should be tested and runnable.

5. Optimize for search — Write the title using the exact phrasing customers use (check search analytics). Front-load keywords in the first sentence. Add metadata tags for category, product area, and plan tier. Include common alternate phrasings as a "Also known as" line or in the article metadata. Keep URLs clean and human-readable.

6. Review for accuracy and clarity — Have a subject matter expert verify technical accuracy. Run a readability check targeting grade 8 reading level. Ensure every step is testable by someone with no prior context. Check that screenshots match the current UI. Validate all links. Set a review-by date (typically 90 days or on next product release affecting the topic).

Usage