help-docs-writer

帮助文档撰写助手

为产品功能编写面向客户的帮助文章，连接技术实现与通俗易懂的文档。

输入

使用 AskUserQuestion 收集以下信息：

输入	必填	说明
功能名称	是	要编写文档的功能
目标受众	是	技术水平（初级／中级／高级）
输出格式	否	markdown（默认）或 html
帮助中心平台	否	Zendesk、Intercom、Notion、GitBook、自定义平台

流程

1. 功能探索

在代码库中搜索功能实现：

# 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/

提取以下信息：

• 功能的作用（核心功能）
• 用户可见的入口（按钮、菜单、URL）
• 配置选项
• 错误状态和边缘情况

2. 组织文章结构

标准帮助文章结构：

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. 面向客户撰写

• 使用第二人称（“你”）、现在时和主动语态，避免行话
• 编号步骤：每步只包含一个操作，以动词开头，并在每个操作后说明预期结果

文章模板

功能指南

# 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]

快速参考

适用于简单功能：

# [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]

设置／配置指南

# [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].

写作指南

步骤说明

推荐写法	避免写法
点击 Save	点击 Save 按钮
选择你的时区	选择你想要的时区
输入你的电子邮件	键入你的电子邮件地址

UI 元素格式

• 用 粗体 标示可点击元素：按钮、链接、菜单项
• 用 Code 标示用户输入、URL 或技术值
• 用 斜体 强调内容（谨慎使用）
• 用“引号”标示用户应看到的确切文本

截图占位符

添加占位符，提供视觉指引：

![Screenshot: Settings page with Save button highlighted]

格式：![Screenshot: [description of what to capture and highlight]]

提示框

用于展示重要信息：

> **Note:** [Important information]

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

> **Tip:** [Helpful suggestion]

输出格式

Markdown（默认）

标准 Markdown，包含：

• ATX 标题（#、##、###）
• 围栏代码块
• 表格
• 用于提示内容的引用块

HTML

使用语义化 HTML，包含：

• <article> 包装元素
• <h1> 至 <h3> 标题
• 用于编号步骤的 <ol>
• 用于数据的 <table>
• 带有 class="note|warning|tip" 的 <aside> 提示框
• 移除内联样式（仅使用 CSS 类）

HTML 模板：

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

质量检查清单

交付前，请确认：

• 标题以动作动词或 “How to” 开头
• 概述说明了是什么，以及为什么（带来的好处）
• 列出了所有前提条件
• 每个步骤只包含一个操作
• 步骤以动词开头
• UI 元素使用 粗体
• 不含行话或未定义的缩写
• 故障排除部分涵盖常见问题
• 包含截图占位符
• 链接到相关文章

平台专属说明

Zendesk

• 使用 {{snippet}} 插入可重复使用的内容
• 在元数据中添加文章标签
• 添加搜索关键词

Intercom

• 文章长度控制在 1000 个词以内
• 使用其提示框语法：> 📌 Note:
• 在末尾添加互动提示

Notion

• 使用折叠块展示故障排除内容
• 添加目录
• 使用带图标的提示框

GitBook

• 使用提示语法：{% hint style="info" %}
• 添加页面描述
• 使用标签页展示多平台说明

此技能不会执行的操作

• 生成截图（仅提供占位符）
• 翻译成其他语言
• 创建视频教程
• 编写 API 文档（技术文档请使用 docs-architect）