help-center-article

name	help-center-article
description	Writes help center articles with step-by-step instructions, screenshot placeholders, and troubleshooting sections for customer self-service.
allowed-tools	Read Write Glob
metadata	{"author":"matthewhitcham","version":"1.0"}

Help Center Article

When to Use This Skill

Use this skill when you need to:

• Write a customer-facing help center or knowledge base article
• Create step-by-step instructions with screenshot placeholders
• Build troubleshooting guides for common customer issues
• Reduce support ticket volume by enabling self-service

DO NOT use this skill for internal SOPs (use knowledge-base-builder), blog posts, or support response templates. This is for customer-facing self-service documentation.

---

Core Principle

A HELP CENTER ARTICLE SHOULD ANSWER THE CUSTOMER'S QUESTION WITHOUT THEM NEEDING TO CONTACT SUPPORT — IF THEY STILL NEED TO EMAIL YOU AFTER READING IT, THE ARTICLE FAILED.

---

Phase 1: Article Brief

Define what the article will cover and for whom.

Required Inputs

Input	What to Ask	Default
Topic	"What question or task does this article address?"	No default
Audience	"What is the customer's technical skill level?"	Beginner-friendly
Article type	"Is this a how-to, troubleshooting guide, FAQ, or conceptual explainer?"	How-to
Related articles	"Are there any related articles to link to?"	None
Common mistakes	"What do customers get wrong most often with this?"	No default

GATE: Confirm the article brief before writing.

---

Phase 2: Write Article

Create the article following help center best practices.

How-To Article Template

# How to [Task Name]

**Last updated:** [Date]
**Applies to:** [Plan level / product version / user role]
**Time required:** [X minutes]

## Overview

[1-2 sentences: what this article covers and the end result]

## Before You Start

- [Prerequisite 1 — what the customer needs before beginning]
- [Prerequisite 2]

## Steps

### Step 1: [Action]

[1-2 sentences of instruction]

[Screenshot: Description of what the customer should see]

### Step 2: [Action]

[1-2 sentences of instruction]

[Screenshot: Description of what the customer should see]

### Step 3: [Action]

[1-2 sentences of instruction]

**Result:** [What the customer should see when they complete this step]

## Troubleshooting

### [Common problem 1]

**Symptom:** [What the customer sees]
**Cause:** [Why it happens]
**Fix:** [Step-by-step solution]

### [Common problem 2]

**Symptom:** [What the customer sees]
**Fix:** [Solution]

## Related Articles

- [Article title and link]
- [Article title and link]

## Still Need Help?

If these steps did not resolve your issue, [contact support link] and include:
- [Info to include: screenshots, error messages, account details]

Troubleshooting Guide Template

# Troubleshooting: [Issue Name]

## Quick Fixes

Try these first (most issues resolve here):

1. [Quick fix 1 — e.g., "Clear your browser cache and refresh"]
2. [Quick fix 2 — e.g., "Log out and log back in"]
3. [Quick fix 3]

## Detailed Solutions

### If you see [Error/Symptom A]

**Cause:** [Explanation]
**Fix:**
1. [Step]
2. [Step]

### If you see [Error/Symptom B]

**Cause:** [Explanation]
**Fix:**
1. [Step]
2. [Step]

## Still Not Working?

Contact support at [link] with:
- What you were trying to do
- The exact error message (screenshot preferred)
- Your browser and device type

GATE: Present the article draft for review.

---

Phase 3: Optimize

Improve the article for findability and usability.

SEO and Search Optimization

• Title: Use the exact words customers would search for
• Meta description: Summarize the answer in 1 sentence
• Tags/categories: Add relevant tags for internal search

Readability Checklist

- [ ] Title matches what a customer would type into a search bar
- [ ] Steps are numbered and each step has ONE action
- [ ] Screenshots (or placeholders) show what the customer should see
- [ ] No jargon — if a technical term is necessary, define it
- [ ] Article is under 500 words (longer articles should be split)
- [ ] Troubleshooting section covers the top 2-3 issues
- [ ] "Still need help?" section includes clear contact path
- [ ] Related articles are linked for deeper exploration

Writing Rules

• Use "you" language: "Click the Settings button" not "The user should click Settings"
• One action per step — never combine two actions in one step
• Bold the clickable element: "Click Save Changes"
• Use present tense: "The page displays..." not "The page will display..."
• Include what success looks like: "You should see a green confirmation message"

---

Phase 4: Maintain

Keep articles accurate and relevant.

Maintenance Triggers

Update the article when:

• The product UI changes
• A new feature affects the workflow
• Support tickets reference this article with confusion
• Screenshots become outdated

Performance Metrics

| Metric | Target | Current |
|--------|--------|---------|
| Article views per month | Trending up | — |
| Support tickets on this topic | Trending down | — |
| Article helpfulness rating | 80%+ positive | — |
| Average time on article | 1-3 minutes | — |

---

Anti-Patterns

• Wall of text without steps — customers scan, they do not read paragraphs. Use numbered steps and headers.
• Assuming knowledge — "Navigate to the API settings" assumes the customer knows what an API is and where to find it.
• Outdated screenshots — nothing erodes trust faster than instructions that do not match what the customer sees.
• Burying the answer — put the most common solution first. Do not make customers read 500 words to find a 1-sentence fix.
• No escape hatch — every article needs a "Still need help? Contact us" at the bottom.

---

Recovery

• Customers still contact support about a documented topic: The article is hard to find, hard to understand, or missing a common scenario. Review and revise.
• User has no screenshots yet: Use description placeholders: [Screenshot: The Settings page with the "Billing" tab highlighted]. Add actual screenshots later.
• Article is too long: Split into multiple articles. A how-to and a troubleshooting guide are better as two articles than one mega-article.
• User does not know what to document first: Start with the top 5 support ticket topics. Each one becomes an article.
• Help center gets no traffic: Link to relevant articles in onboarding emails, support responses, and product UI.