support-docs

支持文档

适用场景

当创始人或团队成员需要创建面向客户的文档，帮助用户独立解决问题时启用。适用于“撰写一篇帮助中心文章”“创建常见问题解答”“编写我们的 API 文档”“撰写故障排除指南”“制作入门指南”或“我们的支持工单总是在问相同的问题”等请求。

所需背景信息

• **来自 startup-context：**产品类型、目标用户的技术水平、现有文档（如有）、主要支持工单类别，以及用于托管文档的工具（例如 Notion、GitBook、Zendesk、ReadMe）。
• **来自用户：**要编写文档的具体主题、目标受众（终端用户、管理员、开发者）、用户的技术水平、常见故障模式或易引起困惑的地方，以及这是新文章还是对现有内容的更新。

工作流

1. 确定文档类型 — 判断适用哪种模板：帮助中心文章、常见问题解答、故障排除指南、API 参考或入门指南。每种文档对应不同的用户意图。
2. 确定用户的入口 — 用户会如何找到这篇文档？通过搜索查询、错误消息、支持人员发送的链接，还是应用内帮助按钮？这将决定标题和开篇内容。
3. 按问题—解决方案格式撰写 — 先说明用户遇到的问题（使用用户自己的说法），再提供解决方案。切勿以产品架构说明开篇。
4. 循序渐进地呈现信息 — 优先提供最常见问题的答案。将边缘情况、高级选项和技术细节放入可展开的部分，或放在文章后面。
5. 添加便于搜索的内容 — 包含用户会搜索的确切错误消息、功能名称和口语化词语。自然地重复关键术语。
6. 按照“凌晨 3 点规则”测试 — 假设自己是一位凌晨 3 点遇到工作流故障、心情沮丧的用户，阅读这篇文章。它能否在 2 分钟内帮你找到解决方案？如果不能，就重新组织内容。
7. 链接相关文章 — 在底部添加“相关文章”或“后续步骤”链接，帮助用户继续自助解决问题。

输出格式

采用以下五种模板之一撰写 Markdown 文档。每篇支持文档都应能在 30 秒内浏览完毕，并能在 2 分钟内找到解决方案。

模板 1：帮助中心文章

# [Action-oriented title: "How to X" or "Setting up Y"]

[One sentence describing what this article helps you do.]

## Before You Start
- Prerequisites or permissions needed

## Steps
1. Action step with specific UI path (Settings > Integrations > Slack)
2. Next action step
   > **Note:** Important callout for common mistakes

## Frequently Asked Questions
**Q: Common question about this feature?**
A: Direct answer.

## Still Need Help?
Contact support at [link] or chat with us in-app.

模板 2：故障排除指南

# Troubleshooting: [Problem in user's words]

## Symptoms
What the user sees when this problem occurs (exact error messages in code blocks).

## Quick Fix
The solution that works 80% of the time. Put this first.

## If That Didn't Work
### Cause 1: [Most common cause]
How to diagnose → How to fix

### Cause 2: [Second most common]
How to diagnose → How to fix

## Collect Information for Support
If none of the above worked, gather these details before contacting support:
- [Specific data point 1]
- [Specific data point 2]

模板 3：常见问题页面

按类别对问题分组（入门、常见问题、账单）。每个答案为 1-3 句话；如果答案需要更多细节，则附上完整文章的链接。

模板 4：API 文档

结构：端点和方法、身份验证、请求参数（包含名称/类型/是否必需/说明的表格）、请求示例（可运行的 curl）、响应示例（成功响应及每种错误代码的响应）和速率限制。每段代码都必须可直接复制粘贴并正常运行。

模板 5：入门指南

结构：包含预期成果和所需时间的欢迎语、3-5 个连续步骤（每步说明操作及其重要性）、验证环节（“现在你应该能看到 X”），以及指向更深入功能的“后续内容”链接。

框架与最佳实践

问题—解决方案—验证模式

每篇支持文档都应遵循以下流程：

1. **问题：**说明用户想要完成什么，或出了什么问题（使用用户的说法，而非内部术语）。
2. **解决方案：**按顺序提供修复方法或步骤，并写明准确的界面路径以及每一步的预期结果。
3. **验证：**告诉用户如何确认问题已解决。“现在你应该能在 Y 页面上看到 X。”

可搜索性原则

• 标题应与搜索查询匹配。 使用“如何将数据导出为 CSV”，而不是“数据导出功能概览”。
• 逐字包含错误消息。 如果用户看到 Error 403: Insufficient permissions，故障排查指南中就必须出现这条原文。
• 同时使用技术术语和通俗说法。 写上“单点登录（SSO）”，这样搜索“SSO”和“单点登录”都能找到这篇文章。
• 把答案放在前面。 在前 100 个词内给出解决方案。许多用户根本不会向下滚动。

渐进式披露规则

• 第 1 层（可见）： 适用于 80% 用户的答案。
• 第 2 层（可展开）： 边缘情况、高级配置和特定平台的差异。
• 第 3 层（链接）： 深入的技术细节、架构说明和完整 API 参考。
• 不要让普通用户为了获得简单答案而先阅读高级内容。

写作风格与维护

• 使用第二人称和现在时。 写“点击 Save”，不要写“你将点击 Save”。写“你可以”，不要写“用户可以”。
• 提供具体的 UI 路径。 写“转到 Settings > Team > Permissions”，不要写“导航到团队设置”。
• 先展示操作，再解释。 先给出操作步骤，再补充背景。用户想先解决问题，再了解原因。
• 术语保持一致。 如果 UI 使用“Workspace”，文档中就绝不要称之为“Organization”。
• 为每篇文章添加标签和日期。 过时的文档比没有文档更糟糕。每次产品发布时都要检查文档。
• 跟踪问题转移率。 如果帮助文章没有减少相关主题的支持工单，就重写它。
• 添加反馈组件。 “这篇内容有帮助吗？是 / 否”——将“否”的回复转给文档负责人。

相关技能

• process-docs — 当支持主题需要内部 SOP 来处理仅靠面向客户的文档无法解决的边缘情况或升级问题时，串联此技能。
• onboarding-flow — 创建作为新用户引导体验一部分的入门指南时，串联此技能。

示例

示例 1：故障排查指南

用户：“用户一直给我们发邮件，说无法连接他们的 Slack 集成。请写一份故障排查指南。”

良好输出摘录：

故障排查：无法连接 Slack 集成

症状

点击“Connect to Slack”时，你会看到以下错误之一：

• Authorization failed. Please try again.
• 页面重定向回 Settings，但没有显示确认消息。
• Slack 已打开，但显示“This app is not approved by your workspace admin.”。

快速修复

1. 尝试使用其他浏览器。 浏览器扩展（尤其是广告拦截器）可能会干扰 OAuth 重定向。打开无痕/隐私窗口后重试。
2. 检查你的 Slack 权限。 你必须是 Slack Workspace Admin 或 Owner。请 Slack 管理员授予你权限，或请他们完成连接。

如果仍未解决

原因：Slack 工作区限制

你的 Slack 工作区可能要求管理员批准新应用。

• 诊断： 如果你看到“This app is not approved by your workspace admin.”，原因就在于此。
• 修复： 请 Slack 管理员前往 Slack Admin > Apps > Manage > 搜索“[Product Name]” > Approve，批准我们的应用。

示例 2：API 文档

用户：“为我们的 webhook 端点编写文档。它接受包含事件数据的 POST 请求，并在成功时返回 200。”

良好的输出方式： 严格遵循 API 模板。包括身份验证详情、每个参数的类型及必填/可选状态、可运行的 curl 示例、所有响应代码及其说明、速率限制和重试策略。开发者会从本文档中复制粘贴内容，因此每段代码都必须能正常运行。