name: Help Article Writer
slug: help-article-writer
description: Write clear, effective help center articles that reduce support tickets and empower users
category: customer-support
complexity: moderate
version: "1.0.0"
author: "ID8Labs"
triggers:
- "help article"
- "help center"
- "documentation"
- "knowledge base"
- "support article"
- "user guide"
tags:
- help-center
- documentation
- technical-writing
- knowledge-base
- customer-support

Help Article Writer

Expert help center content creation system that transforms complex product knowledge into clear, scannable, user-friendly documentation. This skill provides structured workflows for planning, writing, formatting, and optimizing help articles that actually help users succeed.

Help articles are the bridge between your product and user success. Well-written documentation reduces support burden, accelerates user adoption, and builds product confidence. This skill helps you create help content that users can find, understand, and act on.

Built on technical writing best practices and user experience principles, this skill combines content strategy, clear writing, and continuous optimization to create help centers that scale.

Core Workflows

Workflow 1: Content Planning

Map what needs to be documented and prioritize

1. Content Audit
2. Inventory existing help content
3. Identify gaps vs. product features
4. Flag outdated content needing updates
5. Map content to user journeys

6. Prioritize by support ticket volume

7. User Journey Mapping

8. Document key user flows
9. Identify decision points needing guidance
10. Note complexity spikes requiring documentation
11. Map onboarding to documentation needs

12. Align with feature adoption goals

13. Content Hierarchy

14. Getting Started: First-time user needs
15. Core Features: Main functionality guides
16. Advanced Features: Power user documentation
17. Integrations: Third-party connections
18. Account & Billing: Administrative needs

19. Troubleshooting: Problem resolution

20. Priority Matrix
    | Priority | Criteria |
    |----------|----------|
    | Critical | High ticket volume, core features, onboarding |
    | High | Moderate tickets, important features |
    | Medium | Low tickets, nice-to-have features |
    | Low | Edge cases, rarely used features |

Workflow 2: Article Structure

Design articles for scannability and comprehension

1. Standard Article Template
   ```
   # [Clear, Action-Oriented Title]

[One-sentence summary of what this article covers]

## Overview
[Brief context - what, why, who needs this]

## Prerequisites
[What users need before starting - optional]

## Steps / How It Works
[Numbered steps or explanation]

## Examples
[Concrete examples if helpful]

## Common Issues
[Troubleshooting section if relevant]

## Related Articles
[Links to related content]
```

1. Article Types
2. Conceptual: Explains what something is and why it matters
3. Procedural: Step-by-step how-to guides
4. Reference: Technical specifications, API docs
5. Troubleshooting: Problem-solution format

6. Tutorial: Learning-focused walkthroughs

7. Formatting Standards

8. H1 for title only
9. H2 for main sections
10. H3 for subsections
11. Numbered lists for sequential steps
12. Bullet lists for non-sequential items
13. Callouts for warnings, tips, notes

Workflow 3: Writing Process

Create clear, user-focused content

1. Pre-Writing
2. Define the user and their goal
3. Identify the user's starting knowledge
4. Determine success criteria
5. Gather technical information

6. Test the process yourself

7. Drafting

8. Start with the user's goal, not the feature
9. Write in second person ("you")
10. Use active voice
11. Keep sentences under 25 words
12. One idea per paragraph

13. Lead with the action

14. Editing Passes

15. Clarity pass: Simplify jargon, shorten sentences
16. Accuracy pass: Verify all steps work
17. Formatting pass: Add headers, lists, callouts
18. Link pass: Add internal/external links

19. Visual pass: Add screenshots, diagrams

20. Quality Checklist

21. [ ] Title clearly states what user will accomplish
22. [ ] Overview provides context in 2-3 sentences
23. [ ] Steps are numbered and specific
24. [ ] Screenshots show current UI
25. [ ] No jargon without explanation
26. [ ] Includes troubleshooting for common issues
27. [ ] Links to related content
28. [ ] Tested by non-expert

Workflow 4: Visual Content

Enhance articles with effective imagery

1. Screenshot Guidelines
2. Capture only relevant UI areas
3. Use consistent browser/device
4. Annotate with numbered callouts
5. Highlight clickable elements
6. Maintain consistent dimensions

7. Update when UI changes

8. Diagram Guidelines

9. Use for complex flows or architectures
10. Keep visual style consistent
11. Include legend if needed
12. Make text readable at small sizes

13. Provide alt text for accessibility

14. Video Guidelines

15. Keep under 3 minutes
16. Use for complex multi-step processes
17. Include captions
18. Provide text alternative

19. Host on reliable platform

20. Visual Placement

21. Screenshots after the step they illustrate
22. Diagrams at concept introduction
23. Videos as optional enhancement, not replacement

Workflow 5: Optimization & Maintenance

Keep content fresh and effective

1. SEO Optimization
2. Include keywords in title and headers
3. Write descriptive meta descriptions
4. Use natural language (matches search queries)
5. Internal linking structure

6. Alt text for images

7. Analytics Tracking

8. Page views and unique visitors
9. Time on page
10. Bounce rate
11. Search terms leading to article
12. "Was this helpful?" feedback

13. Exit to support ticket rate

14. Update Triggers

15. Product UI changes
16. Feature updates or deprecations
17. User feedback indicating confusion
18. Support ticket patterns

19. Negative helpfulness ratings

20. Review Cadence

21. On Release: Update affected articles
22. Monthly: Review feedback and metrics
23. Quarterly: Comprehensive content audit
24. Annually: Full restructure if needed

Quick Reference

Best Practices

Writing Style

• Write at 8th grade reading level
• Use familiar words over technical terms
• Define acronyms on first use
• One instruction per step
• Start steps with verbs
• Avoid "simple," "just," "easy"

Structure

• Front-load the most important information
• Keep articles focused (one topic per article)
• Use parallel structure in lists
• Limit nesting to 2 levels
• Include jump links for long articles

User Experience

• Make articles findable via search
• Provide multiple navigation paths
• Include breadcrumbs
• Link related content
• Enable feedback mechanism
• Offer escalation path to support

Accessibility

• Alt text for all images
• Descriptive link text (not "click here")
• Sufficient color contrast
• Keyboard-navigable
• Screen reader compatible
• Captions for videos

Maintenance

• Assign article ownership
• Create update alerts for product changes
• Track content freshness dates
• Archive rather than delete
• Version control important articles

Article Templates

Procedural Article

# How to [Accomplish Specific Goal]

Learn how to [brief description of what user will accomplish].

## Overview

[2-3 sentences explaining what this feature/process does and why a user would want to do this]

## Before You Start

- [Prerequisite 1]
- [Prerequisite 2]

## Steps

### Step 1: [Action]

[Explanation of what to do]

![Screenshot with annotation]

### Step 2: [Action]

[Explanation of what to do]

### Step 3: [Action]

[Explanation of what to do]

## Verify It Worked

You'll know you're successful when [observable outcome].

## Troubleshooting

**Issue**: [Common problem]
**Solution**: [How to fix it]

## What's Next

- [Related action 1]
- [Related action 2]

---
*Last updated: [Date] | [Feedback link]*

Conceptual Article

# Understanding [Concept]

[One-sentence definition of the concept]

## What Is [Concept]?

[2-3 paragraphs explaining the concept in user terms]

## Why It Matters

[Explain the benefit to the user - what problem it solves]

## How It Works

[Explain the mechanism at appropriate technical level]

![Diagram if helpful]

## Key Terms

| Term | Definition |
|------|------------|
| [Term 1] | [Definition] |
| [Term 2] | [Definition] |

## Examples

### Example 1: [Scenario]
[Concrete example of concept in action]

### Example 2: [Scenario]
[Another example]

## Related Topics

- [Related concept 1]
- [Related concept 2]

---
*Last updated: [Date] | [Feedback link]*

Troubleshooting Article

# Fixing [Problem Description]

Having trouble with [problem]? Here's how to resolve it.

## Symptoms

You might see this issue if:
- [Symptom 1]
- [Symptom 2]
- [Symptom 3]

## Quick Fixes

Try these solutions in order:

### Solution 1: [Most Common Fix]

[Steps to try]

### Solution 2: [Second Most Common]

[Steps to try]

### Solution 3: [Less Common]

[Steps to try]

## Still Having Issues?

If none of the above worked:

1. [Gather this information]
2. [Contact support] with details

## Why This Happens

[Brief technical explanation for curious users - optional]

## Prevent It in the Future

[Tips to avoid this issue - if applicable]

---
*Last updated: [Date] | [Feedback link]*

Red Flags

• Wall of text: No headers, bullets, or visual breaks
• Passive voice: "The button should be clicked" vs "Click the button"
• Feature-centric: Describes feature, not user goal
• Outdated screenshots: UI doesn't match current product
• Missing context: Assumes too much user knowledge
• No escalation: User stuck with no next step
• Buried answer: Key information hidden in prose

Content Style Guide

Voice and Tone

• Friendly but not casual
• Confident but not arrogant
• Helpful but not condescending
• Clear but not oversimplified

Word Choices

Formatting

• Bold for UI elements users interact with
• Code formatting for user input, code, paths
• Italics sparingly for emphasis

• Blockquotes for important callouts