Help Documentation Writer Skill

Help Documentation Writer

Create customer-facing help articles for product features. Bridges technical implementation with user-friendly documentation.

Inputs

Use AskUserQuestion to gather:

| Input | Required | Description | |-------|----------|-------------| | Feature name | Yes | What feature to document | | Target audience | Yes | Technical level (beginner/intermediate/advanced) | | Output format | No | markdown (default) or html | | Help center platform | No | Zendesk, Intercom, Notion, GitBook, custom |

Process

1. Feature Discovery

Search codebase for feature implementation:

# Find feature files
rg -l "feature_name" --type-add 'code:*.{rb,js,ts,py,jsx,tsx}'

# Find UI components
rg -l "FeatureName" src/ app/

# Find routes/endpoints
rg "feature" config/routes.rb app/controllers/

Extract:

What the feature does (core functionality)
User-facing entry points (buttons, menus, URLs)
Configuration options
Error states and edge cases

2. Structure the Article

Standard help article structure:

1. Title (action-oriented)
2. Overview (what + why, 2-3 sentences)
3. Prerequisites (if any)
4. Step-by-step instructions
5. Tips/best practices (optional)
6. Troubleshooting (common issues)
7. Related articles (links)

3. Write for Customers

Second person ("you"), present tense, active voice, no jargon
Numbered steps: one action per step, start with verb, include expected result after each action

Article Templates

Feature Walkthrough

# How to [Action] with [Feature]

[One sentence: what this helps you do]

## Before you start

- [Prerequisite 1]
- [Prerequisite 2]

## Steps

1. **[Action verb] [object]**

   [Where to find it / what to click]

   ![Screenshot placeholder: description]

2. **[Next action]**

   [Details]

3. **[Final action]**

   You'll see [confirmation message/result].

## Tips

- [Tip 1]
- [Tip 2]

## Troubleshooting

### [Problem statement as question]

[Solution in 1-2 sentences]

### [Another common issue]

[Solution]

## Related articles

- [Link to related feature]
- [Link to related feature]

Quick Reference

For simple features:

# [Feature Name]

[What it does in one sentence]

**To use [feature]:**

1. Go to **[Location]**
2. Click **[Button/Link]**
3. [Complete the action]

**Note:** [Important caveat if any]

Settings/Configuration Guide

# [Feature] settings

Customize how [feature] works for your account.

## Available settings

| Setting | Description | Default |
|---------|-------------|---------|
| [Name] | [What it controls] | [Value] |
| [Name] | [What it controls] | [Value] |

## How to change settings

1. Go to **Settings > [Section]**
2. Find **[Setting name]**
3. [Instructions to modify]
4. Click **Save**

Changes take effect [immediately/after X].

Writing Guidelines

Step Instructions

| Do | Don't | |----|-------| | Click Save | Click on the Save button | | Select your timezone | Choose the timezone you want | | Enter your email | Type in your email address |

UI Element Formatting

Bold for clickable elements: buttons, links, menu items
Code for user input, URLs, or technical values
Italics for emphasis (sparingly)
"Quotes" for exact text the user should see

Screenshot Placeholders

Include placeholders for visual guidance:

![Screenshot: Settings page with Save button highlighted]

Format: ![Screenshot: [description of what to capture and highlight]]

Callouts

Use for important information:

> **Note:** [Important information]

> **Warning:** [Potential issue or destructive action]

> **Tip:** [Helpful suggestion]

Output Formats

Markdown (default)

Standard markdown with:

ATX headings (#, ##, ###)
Fenced code blocks
Tables
Blockquotes for callouts

HTML

Semantic HTML with:

<article> wrapper
<h1> through <h3> headings
<ol> for numbered steps
<table> for data
<aside> for callouts with class="note|warning|tip"
Inline styles stripped (CSS classes only)

HTML Template:

<article class="help-article">
  <h1>[Title]</h1>

  <p class="intro">[Overview]</p>

  <section class="prerequisites">
    <h2>Before you start</h2>
    <ul>
      <li>[Prerequisite]</li>
    </ul>
  </section>

  <section class="steps">
    <h2>Steps</h2>
    <ol>
      <li>
        <strong>[Action]</strong>
        <p>[Details]</p>
      </li>
    </ol>
  </section>

  <section class="troubleshooting">
    <h2>Troubleshooting</h2>
    <details>
      <summary>[Problem as question]</summary>
      <p>[Solution]</p>
    </details>
  </section>

  <aside class="note">
    <p>[Important note]</p>
  </aside>
</article>

Quality Checklist

Before delivery, verify:

[ ] Title starts with action verb or "How to"
[ ] Overview explains what AND why (benefit)
[ ] Prerequisites listed if any
[ ] Each step = one action
[ ] Steps start with verbs
[ ] UI elements in bold
[ ] No jargon or undefined acronyms
[ ] Troubleshooting covers common issues
[ ] Screenshot placeholders included
[ ] Related articles linked

Platform-Specific Notes

Zendesk

Use {{snippet}} for reusable content
Add article labels in metadata
Include search keywords

Intercom

Keep articles under 1000 words
Use their callout syntax: > 📌 Note:
Add reaction prompts at end

Notion

Use toggle blocks for troubleshooting
Add table of contents
Use callout blocks with icons

GitBook

Use hints syntax: {% hint style="info" %}
Add page descriptions
Use tabs for multi-platform instructions

What This Skill Does NOT Do

Generate screenshots (provides placeholders only)
Translate to other languages
Create video tutorials
Write API documentation (use docs-architect for technical docs)

Agent Skills: Help Documentation Writer

Install this agent skill to your local

Skill Files