help-docs-writer

Help Documentation Writer

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

Inputs

Use AskUserQuestion to gather:

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

Language rules:

• Second person ("you") throughout
• Present tense for instructions
• Active voice only
• No jargon — explain technical terms if unavoidable
• Short sentences (max 20 words)

Instruction format:

• Numbered steps for sequences
• One action per step
• Start each step with a verb
• Include what the user should see 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

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

Example Output

Input: Document the "Export to CSV" feature

Output (Markdown):

# How to export your data to CSV

Download your data as a CSV file to use in spreadsheets or other tools.

## Before you start

- You need **Editor** or **Admin** permissions
- Exports include data from the last 90 days by default

## Steps

1. **Go to Reports**

   Click **Reports** in the left sidebar.

   ![Screenshot: Left sidebar with Reports highlighted]

2. **Select the data to export**

   Use the filters to narrow down your data. You can filter by:
   - Date range
   - User
   - Status

3. **Click Export**

   Click the **Export** button in the top right corner.

   ![Screenshot: Export button location]

4. **Choose CSV format**

   Select **CSV** from the dropdown menu.

5. **Download your file**

   Your browser will download a file named `export-[date].csv`.

## Tips

- Large exports (over 10,000 rows) may take a few minutes
- The CSV uses UTF-8 encoding — compatible with Excel, Google Sheets, and Numbers

## Troubleshooting

### The Export button is grayed out

You don't have permission to export. Ask an Admin to grant you Editor access.

### My export is missing data

Check your date range filter. The default is 90 days. Adjust it to include older data.

### The file won't open in Excel

The file may be too large. Try opening it in Google Sheets, or filter your export to reduce the size.

## Related articles

- [Understanding your Reports dashboard](#)
- [Filtering and sorting data](#)
- [User permissions guide](#)

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)