knowledge-base-article-writing

知识库文章撰写

撰写精良的帮助中心文章和常见问题解答，通过为客户提供清晰、可自行查阅的答案来减少支持工单。此技能可将支持工单模式、产品变更和常见问题转化为结构化文章，优化可读性、搜索效果和浏览体验，并遵循分步指南、故障排查流程和参考资料的文档最佳实践。

工作流程

1. 从支持数据中确定主题 — 分析支持工单趋势、搜索分析数据（客户搜索但未找到结果的内容）和 CSM 反馈，找出影响最大的主题。根据工单数量（涵盖前 10 个问题类别的文章能减少最多工单）、主题复杂度（复杂主题最适合编写指南）和时效性（新功能或近期变更需要立即编写文档）确定优先级。

2. 研究解决方案 — 从工程文档、内部 Wiki、产品规格和主题专家处收集权威答案。在产品中亲自端到端测试工作流程，验证准确性。记录当前产品版本中显示的确切 UI 文案、按钮标签和导航路径。注明任何前提条件、所需权限或套餐级别限制。

3. 组织文章结构 — 使用统一模板：标题（以操作为导向，符合客户的搜索方式）、摘要（便于浏览的 1-2 句答案）、前提条件（读者开始前需要准备的内容）、步骤（编号列出，每步执行一项操作并说明预期结果）、故障排查（常见错误及其解决方法）和相关文章（指向相关主题的链接）。保持层级扁平——主要章节使用 H2，谨慎使用 H3。

4. 添加视觉辅助内容和代码示例 — 对于 UI 操作较多的工作流程，添加截图（使用与步骤对应的编号标注）；对于 API 或 CLI 工作流程，添加代码片段（包含语言标签、复制按钮和预期输出）；对于架构或流程说明，添加示意图。每张图片都应包含替代文本。每个代码块都应经过测试并可运行。

5. 优化搜索效果 — 使用客户实际采用的措辞撰写标题（查看搜索分析数据）。在首句前置关键词。添加类别、产品领域和套餐级别的元数据标签。将常见的其他说法列为“也称为”一行或加入文章元数据。保持 URL 简洁易读。

6. 检查准确性和清晰度 — 请主题专家验证技术准确性。进行可读性检查，目标为 8 年级阅读水平。确保没有先前背景知识的人也能测试每个步骤。检查截图是否与当前 UI 一致。验证所有链接。设置复查日期（通常为 90 天后，或下次影响该主题的产品发布时）。

用法

描述文章主题、目标受众以及需要包含的具体细节。Agent 会撰写完整、可直接发布的文章。

Write a help center article for "How to set up SSO with SAML." Target audience
is IT admins. Our product supports Okta, Azure AD, and OneLogin. Include
troubleshooting for common SAML errors.

示例

示例 1：操作指南文章 — 使用 SAML 设置 SSO

输入： 面向 IT 管理员的 SSO/SAML 设置指南。

输出：

---

如何使用 SAML 设置单点登录（SSO）

启用基于 SAML 的 SSO，让团队成员可以使用公司的身份提供商登录。支持的提供商：Okta、Azure AD 和 OneLogin。

前提条件

• 你的账户具有管理员角色（在“设置 → 团队 → 角色”中，你的名字旁边显示“管理员”）
• 可以访问身份提供商的管理控制台
• 你的账户必须使用 Enterprise 方案

步骤

1. 前往 设置 → 安全 → 单点登录，然后点击 配置 SSO。

   [截图：突出显示“安全”标签页并显示 SSO 部分的设置页面]

2. 从下拉菜单中选择你的身份提供商：Okta、Azure AD 或 OneLogin。

3. 复制屏幕上显示的值 — 你需要在身份提供商中使用这些值：

   • ACS URL： https://app.example.com/auth/saml/callback
   • Entity ID： https://app.example.com/saml/metadata
   • RelayState： 除非使用自定义登录页，否则留空

4. 在身份提供商的管理控制台中，使用第 3 步中的值创建新的 SAML 应用。

   Okta： Applications → Create App Integration → SAML 2.0 → 粘贴 ACS URL 和 Entity ID。

   Azure AD： Enterprise Applications → New Application → Create your own → SAML → Basic SAML Configuration → 粘贴相应值。

   OneLogin： Applications → Add App → SAML Custom Connector → Configuration → 粘贴相应值。

5. 从身份提供商下载 Federation Metadata XML 文件，并将其上传到 SSO 配置页面。

6. 设置必需的属性映射：

   email    → user.email       (Required)
   firstName → user.firstName  (Required)
   lastName  → user.lastName   (Required)
   role      → user.role       (Optional — maps to app roles)
   

7. 点击 测试连接。此时会打开一个新的浏览器标签页。使用你的身份提供商凭据登录。如果成功，你会看到“SSO 连接已验证”。

8. 切换 强制使用 SSO，要求所有团队成员通过身份提供商登录。经过 24 小时宽限期后，将禁用非 SSO 登录。

故障排除

错误	原因	解决方法
“SAML 响应签名无效”	元数据 XML 已过期，或来自错误的应用	从 IdP 重新下载元数据 XML 并重新上传
“未找到用户”	SAML 断言中的邮箱与任何账户邮箱都不匹配	检查 IdP 中的邮箱属性映射，确保发送用户的主要邮箱
“检测到时钟偏差”	IdP 与我们的服务之间的服务器时间差超过 5 分钟	确保 IdP 服务器的 NTP 已同步。我们允许 5 分钟的偏差
“受众不匹配”	IdP 中的 Entity ID 与第 3 步中的值不匹配	从“设置 → SSO”复制准确的 Entity ID — 末尾斜杠也很重要
测试通过，但用户无法登录	未启用“强制使用 SSO”，或用户访问了错误的登录 URL	将“设置 → SSO”中的 SSO 登录 URL 分享给团队，并启用“强制使用 SSO”

相关文章

• 管理团队角色和权限
• 设置 SCIM 用户预配
• 配置多重身份验证

---

示例 2：常见问题条目 — 账单问题

输入： 涵盖套餐变更、发票和退款的常见账单问题。

输出：

---

账单常见问题

关于套餐、发票、付款和退款的常见问题解答。

如何升级或降级套餐？

前往 Settings → Billing → Plan，然后点击 Change Plan。选择新套餐并确认。升级会立即生效，你需要为当前账单周期的剩余时间支付按比例计算的费用。降级会在下一个账单周期开始时生效——在此之前，你仍可使用当前套餐的功能。

在哪里可以找到发票？

所有发票都可以在 Settings → Billing → Invoice History 中查看。点击任意发票即可查看或下载 PDF。每次扣款后 24 小时内，发票也会通过电子邮件发送给留存的账单联系人。

如何更新付款方式？

前往 Settings → Billing → Payment Method，然后点击 Update。我们接受 Visa、Mastercard、American Express 和 ACH 银行转账（仅限年度套餐）。新的付款方式将用于所有后续扣款。

我可以申请退款吗？

如果你不满意，我们会在扣款后的 14 天内全额退款。超过 14 天后，我们会按比例将金额抵扣未来的账单。要申请退款，请发送电子邮件至 [email protected]，并提供你的账户邮箱和发票编号。退款会在 5-7 个工作日内处理。

如果付款失败会怎样？

我们会在第 1、3 和 7 天重试失败的付款。每次尝试失败后，你都会收到电子邮件通知。如果 14 天内仍未解决付款问题，你的账户将降级为免费套餐。你的数据会保留 90 天——随时升级即可恢复完整访问权限。

你们提供年度账单折扣吗？

是的。所有付费套餐选择年度账单，相比月度账单可节省 20%。你可以随时在 Settings → Billing → Plan 中切换为年度账单——选择“Annual”后，节省金额会立即生效，任何剩余月度余额都会按比例抵扣。

相关文章

• 了解发票明细项目
• 设置 ACH 银行转账付款
• 管理多个账单账户

---

最佳实践

• 将标题写成问题或操作短语，以匹配客户的搜索方式——“如何设置 SSO”比“SSO 配置指南”更好，因为客户会使用自然语言搜索。
• 一篇文章只讲一个主题。如果一篇文章涵盖两个不同的工作流，就将其拆分。搜索“导出数据”的客户不应该进入一个同时介绍“导入数据”的页面——即使你认为两者相关。
• 每篇文章都以一句直接回答问题的摘要开头。客户是浏览内容，而不是逐字阅读——如果答案就在第一行，即使他们不继续阅读，也能获得所需信息。
• 使用与 UI 标签完全一致的术语。如果按钮上写的是“Configure”，文章中就不要写“Set Up”。文档与 UI 不一致会造成困惑并削弱信任。
• 在每篇文章中注明“上次验证”日期，并在变更日志中更新其涵盖的产品区域时，设置自动提醒。
• 用两个指标跟踪文章效果：搜索到查看率（客户是否找到了文章？）和问题解决率（客户是否在查看文章后的 30 分钟内提交了工单？）。

边缘情况

• 撰写和发布期间产品 UI 发生变化 — 始终等文章文本定稿后再截取屏幕截图。在图片替代文本中注明产品版本号，以便在审查时更容易识别过时的截图。
• 功能仅在某些套餐中提供 — 在顶部添加醒目提示横幅：“此功能适用于 Pro 和 Enterprise 套餐。”不要等读者已经花时间阅读后，才在步骤 4 中提及套餐限制。
• 多语言知识库 — 先用英语撰写规范文章，再进行本地化。不要未经人工审核就通过机器翻译发布——技术术语和 UI 标签必须与本地化产品界面一致。
• 已弃用的功能 — 不要删除介绍已弃用功能的文章。添加弃用提示横幅，注明停用日期并链接到替代文章。旧版套餐的客户可能仍需要旧版文档。
• 多个来源的信息相互冲突 — 当内部文档与产品的实际行为不一致时，以产品行为为准。在产品中进行测试，记录实际情况；如果行为有误，则提交错误报告。