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)

8. 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

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)