Writing Effective Help Articles

Great help articles reduce support volume by letting customers find answers on their own. This guide covers structure, formatting, SEO, and using feedback analytics to improve your articles.

Article Structure

Follow this template for consistency:

1. Title — Clear and specific. Use "How to..." or "Setting up..." format.
2. Introduction (1–2 sentences) — What the article covers and who it's for
3. Prerequisites (if applicable) — What the reader needs before starting
4. Steps — Numbered step-by-step instructions
5. Tips / Best Practices — Additional context or pro tips
6. Related Articles — Links to related content

Markdown Formatting

ChattyPie articles support full Markdown:

Headings

Use ## for major sections and ### for subsections. Avoid # (reserved for the title).

Lists

Use numbered lists for sequential steps and bullet points for non-ordered items.

Tables

| Column 1 | Column 2 |
|----------|----------|
| Data     | Data     |

Code Blocks

Wrap code in triple backticks with an optional language tag:

\`\`\`javascript
const greeting = "Hello!";
\`\`\`

Blockquotes

Use > for callouts, warnings, or notes:

> **Note**: This feature requires a Pro plan.

Writing Tips

• Be concise — Say what needs to be said and stop. Customers want answers, not essays.
• Use bold for UI labels — Write "Click Settings > Billing" so readers can scan for interface elements.
• Include screenshots — A picture is worth a thousand words. Upload images inline.
• Write for scanning — Use short paragraphs, headers, and lists. Most readers scan rather than read word-by-word.
• Avoid jargon — Use simple language. If you must use technical terms, define them.

SEO for Help Articles

Help your articles rank in search engines:

• Title: Include the key search term (e.g. "How to Reset Your Password")
• Meta description: Write a compelling 150-character summary
• Headings: Use descriptive H2/H3 headings that include relevant keywords
• Internal links: Link to related articles to help search engines understand your content structure

Feedback Analytics

Each article shows a "Was this helpful?" prompt. Monitor results in Knowledge Base > Analytics:

• Helpful rate — Percentage of "Yes" votes
• View count — How often the article is read
• Search terms — What people searched for before landing on the article

If an article has a low helpful rate, review and update it. Check the comments for specific feedback.