user-guide-writing

用户指南编写

当交付内容是面向客户或管理员的文档，旨在帮助他们完成产品中的某个工作流时，请使用此技能。

user-guide-writing 是文档集群的核心技能，适用于：

• 入门指南／首次成功指南
• 教程和引导式演练
• 基于任务的操作指南
• 常见问题解答和面向支持场景的答复集
• 产品界面／工作流变更发布后，面向用户的帮助文档更新
• 小型指南集：包含一个主要页面，以及数量最少的配套文档

选择模式或确定范围前，请阅读以下支持文档：

• references/document-modes-and-boundaries.md
• references/mode-structures.md
• references/workflow-checklist.md
• references/maintenance-signals.md

何时使用此技能

• 产品需要一份入门指南，帮助新用户首次成功完成操作。
• 功能发布需要为真实产品用户编写教程或操作指南。
• 帮助中心需要一篇基于任务的文章、常见问题解答或便于排查问题的操作指南。
• 支持问题反复出现，需要将答案整理成长期有效、面向客户的文档。
• 工作流发生变化，需要更新现有的用户操作步骤、截图、警告或前提条件。
• 请求实际需要的是一份指南加一小组配套文档，而不是一份用途混杂的大型文档。

何时不使用此技能

• 主要工作是编写内部规范、架构文档、ADR、运行手册、迁移计划或面向构建者的实施指南 → 使用 technical-writing。
• 主要工作是编写 API 参考、SDK 文档、webhook 文档、开发者快速入门或开发者门户内容 → 使用 api-documentation。
• 主要工作是编写发行说明、CHANGELOG.md、迁移公告或已发布变更摘要 → 使用 changelog-maintenance。
• 主要工作是制作演示文稿、发布演示、研讨会幻灯片或视觉评审材料 → 使用 presentation-builder。
• 主要工作是制定产品定位、营销信息、生命周期邮件文案或发布文案 → 使用 marketing-automation。
• 主要工作是构建应用内引导机制或产品导览体验 → 先使用相关的产品／UX 技能，再使用此技能编写长期有效的配套文档。

指南

步骤 1：确定一种主要模式

起草前，先规范化请求。

user_guide_mode:
  primary_mode: getting-started | tutorial | how-to | faq | release-help-update
  audience: end-user | admin | manager | mixed | unknown
  experience_level: first-time | familiar | advanced | mixed | unknown
  docs_surface: help-center | docs-site | in-app-companion | pdf | unknown
  source_of_truth: product-ui | release-notes | support-tickets | sme-notes | mixed | unknown
  maintenance_need: one-off | recurring | stale-doc-rewrite | launch-critical
  output_shape: single-page | guide-plus-faq | refresh-packet | guide-set | unknown

每次运行只使用一种主要模式：

• getting-started → 以最短路径首次成功完成操作
• tutorial → 提供带有背景信息和里程碑的引导式学习
• how-to → 快速完成一项实用任务
• faq → 简洁列出常见问题，并引导读者查阅更深入的指南
• release-help-update → 在界面或工作流变更发布后，更新面向用户的文档

步骤 2：确认受众、任务和引导方向

写作前，请回答以下问题：

1. 谁会阅读并使用这份文档？他们具有什么角色或权限？
2. 他们应完成什么具体任务或达成什么结果？
3. 哪些前提条件、套餐限制或环境假设可能导致操作流程无法顺利进行？
4. 哪些相邻技能必须排除在范围之外？

快速引导方向对照表：

如果请求的内容类似于……	使用
“编写架构文档／运行手册／迁移计划”	technical-writing
“编写开发者门户／SDK 快速入门／webhook 文档”	api-documentation
“总结本次发布包含哪些内容”	changelog-maintenance
“编写入门文档／教程／常见问题解答／帮助文章”	user-guide-writing
“制作发布演示／培训演示／演练演示文稿”	presentation-builder

步骤 3：收集最少量的面向用户的证据

不要只凭感觉起草。先收集最小且可信的证据集：

• 当前 UI 标签、导航和状态
• 前置条件、权限以及套餐／版本假设
• 每个重要步骤后的预期结果
• 可能的阻碍、空状态和分支条件
• 仅在有助于减少困惑时提供截图或截图占位符
• 可用的支持问题、搜索词或反复出现的故障信号
• 导致当前指南过时的版本变更

如果细节不完整，请明确标注假设，不要假装指南已经过验证。

步骤 4：选择最精简且合适的结构

使用 references/mode-structures.md，并仅保留所选模式需要的章节。

规则：

• 如果请求对应一个用户目标，优先采用单页。
• 如果任务需要一份主指南和常见阻碍说明，采用指南加 FAQ。
• 如果实际工作是发布后修补过时页面，采用更新包，而不是重写整本手册。
• 如果一份草稿同时涉及入门、日常使用、故障排除和发布说明，应拆分为一组精简指南。

步骤 5：输出最精简且实用的文档包

默认输出形式：

• single-page → 一篇入门指南、教程、操作指南或 FAQ 页面
• guide-plus-faq → 一篇主指南，加上一份简短 FAQ 或故障排除附录
• refresh-packet → 变更后的步骤、过时截图清单、受影响的配套文档，以及待验证的假设
• guide-set → 一组范围明确的文档，例如入门指南 + FAQ，或教程 + 后续操作指南

如果请求只需要一页和一份简短的同步清单，就不要提交一份宽泛的手册。

步骤 6：遵循面向用户的文档写作规则

• 从任务和受众入手，而不是实现细节。
• 尽早说明前置条件：角色、权限、套餐限制、所需数据、浏览器／应用／版本假设。
• 优先描述可观察的操作：用户点击、输入、看到和收到的内容。
• 每页只聚焦一个主要目标。
• 指出分支条件，例如特定角色适用的 UI 或替代路径。
• 提供成功检查方式，让用户确认任务已完成。
• 将故障排除内容放在任务附近，不要把它藏在通用附录中。
• 有目的地使用截图，仅在容易困惑的转换步骤处添加，而不是每次点击后都添加。
• 有意链接到其他内容：FAQ → 完整指南，发布帮助更新 → 受影响的文章，入门指南 → 下一项任务。

步骤 7：执行维护和同步检查

定稿前，使用 references/workflow-checklist.md 和 references/maintenance-signals.md。

请确认：

1. 页面类型与用户要完成的任务相符。
2. 前置条件和阻碍说明出现在风险较高的步骤之前。
3. 截图占位符有充分理由且可追踪。
4. 明确列出必须保持同步的相关指南、FAQ、发布更新或支持回复模板。
5. 当请求偏离范围时，仍明确转交给 technical-writing、api-documentation 和 changelog-maintenance。

步骤 8：返回简报或完成的文档

正式起草前，建议采用以下简报格式：

# User Guide Writing Brief

## Mode
- Primary mode:
- Why it fits:
- Audience:
- Output shape:

## Source material used
- Product truth / UI evidence:
- Support or release signals:
- Assumptions / gaps:

## Planned artifact packet
1. main page
2. companion FAQ / refresh list / sync note

## Writing notes
- Key user outcome:
- Known blockers / branching conditions:
- Route-outs kept out of scope:

如果用户已要求提供完成的文档，请直接按相应结构输出选定的页面或文档包。

示例

示例 1：首次成功入门

输入

为新的工作区管理员编写一份入门指南，介绍如何邀请团队成员并创建第一个项目。

理想的输出方向

• 模式：getting-started
• 输出形式：single-page
• 包含前置条件、步骤顺序、成功检查和后续步骤
• 不涉及内部实现说明

示例 2：由版本发布驱动的文档更新

输入

更新我们的报表导出帮助中心文章，因为“导出”按钮已移至“报表”标题栏，现在只有管理员可以选择 XLSX。

良好输出方向

• 模式：release-help-update
• 输出形式：refresh-packet
• 指出 UI 变更、角色差异、截图更新，以及受影响的配套文档
• 不涉及版本发布说明摘要

示例 3：将支持回复转为常见问题

输入

将这些重复的账单支持回复整理成一份面向工作区所有者的简短常见问题解答。

良好输出方向

• 模式：faq
• 输出形式：single-page 或 guide-plus-faq
• 答案简短，必要时链接到更详细的任务指南
• 尽早说明角色／套餐相关的注意事项

示例 4：与开发者文档的边界

输入

更新面向外部开发者的公开 Webhook 快速入门和身份验证故障排除页面。

良好输出方向

• 路由至 api-documentation
• 说明主要工作是发布面向开发者的 API 文档，而不是面向终端用户的产品指南

最佳实践

1. 撰写正文前先选择页面类型。
2. 每页优先聚焦一个用户目标，每次运行优先采用一种主要模式。
3. 使用尽可能精简且实用的文档包，避免编写庞大的全能指南。
4. 在用户遇到阻碍前说明前置条件、权限和限制。
5. 有目的地使用截图，并确保便于更新。
6. 根据支持请求、搜索和版本发布信号，决定接下来要更新什么。
7. 将内部文档、API 文档和版本发布说明转交其他流程处理，不要勉强扩展技能边界。
8. 当页面开始讲解过多任务时，将用途混杂的草稿拆分成一组指南。

参考资料

• Diátaxis
• Google 开发者文档风格指南
• Microsoft 写作风格指南
• GitLab 文档工作流
• Write the Docs — 文档即代码