kb-authoring

文章结构

必备组成部分

每篇知识库文章都包含：

1. 标题：以结果或症状为导向。使用客户会在搜索栏中输入的语言撰写，切勿使用内部行话。
2. 摘要：用 1-2 句通俗易懂的话说明文章涵盖的内容，以及哪些人会从中受益。
3. 正文：按文章类型组织（见下文）。
4. 交叉引用：链接到相关主题的配套文章。
5. 元数据：类别、标签、目标受众、最后修改日期。

格式规范

• 标题（H2、H3）：构建便于浏览的大纲，让读者可以跳转到相关部分。
• 编号列表：用于顺序很重要的有序操作步骤。
• 项目符号列表：用于无序的项目或选项集合。
• 粗体文本：用于界面标签、关键术语和强调内容。
• 代码块：用于命令、API 负载、错误字符串和配置片段。
• 表格：用于并排比较、选项矩阵和参考数据。
• 提示框 / 注意事项：用于警告、提示和必须阅读的注意事项。
• 段落长度：每段不超过 2-4 句。过于密集的段落会让读者望而却步。
• 章节安排：每个章节只讲一个概念。如果一个章节有两个用途，就将其拆分。

提高文章的可查找性

无法通过搜索找到的文章，就等于不存在。

标题构造

有效标题	无效标题	原因
"使用 Okta 设置 SSO"	"SSO 配置"	写出客户会搜索的具体工具名称
"修复：仪表板显示空白页"	"仪表板问题"	与客户遇到的确切症状相符
"API 速率限制和配额参考"	"API 详情"	包含用户查询时使用的精确术语
"错误：导入数据时出现 'Connection refused'"	"导入错误"	包含客户复制到搜索栏中的原始错误字符串

关键词策略

• 嵌入完整错误消息：客户经常会直接将错误文本粘贴到搜索栏中。
• 使用客户的表达方式：使用“无法登录”比“身份验证失败”更容易被搜索到。
• 涵盖同义词：“删除 / 移除”、“主页 / 仪表板”、“下载 / 导出”。
• 提供不同的表述方式：在摘要中从多个角度描述同一个问题。
• 按产品界面区域添加标签：类别和标签应反映客户的认知方式，而非工程部门的组织架构。

开篇句式

每篇文章都应以一个首句开篇，用日常语言重述任务或问题：

• 操作类：“按照以下步骤完成 [X]。”
• 诊断类：“遇到 [症状]？本文将介绍修复方法。”
• 事实类：“[以客户的提问方式表述的问题]？答案如下。”
• 建议类：“一些用户会遇到 [症状]。以下说明原因及解决方法。”

文章模板

操作指南类文章

目标：指导客户从头到尾完成一项任务。

# How to [accomplish task]

[Summary: what this covers and when you would need it]

## Before You Begin

- [Prerequisite 1]
- [Prerequisite 2]

## Instructions

### Step 1: [Action verb phrase]
[Precise instruction with path: Settings > Integrations > API Keys]

### Step 2: [Action verb phrase]
[Instruction, including what the user should see after completing this step]

## Confirm Success

[How to verify the task completed correctly]

## Troubleshooting

- [Potential hiccup]: [Resolution]

## See Also

- [Related article links]

指南：

• 每个步骤都以动词开头。
• 明确说明导航路径：“转到 Settings > Team > Roles。”
• 在关键检查点描述预期结果：“绿色横幅表示保存成功。”
• 根据近期工单解决方案核实说明，或亲自逐步操作一遍。

诊断类（故障排除）文章

目标：帮助客户识别并解决特定故障。

# [Problem statement matching what the user observes]

## What You See

- [Observable symptom 1]
- [Observable symptom 2]

## Why This Happens

[Concise, jargon-free explanation of the root cause]

## How to Fix It

### Fix 1: [Most likely resolution]
[Step-by-step instructions]

### Fix 2: [Alternate resolution if Fix 1 does not apply]
[Step-by-step instructions]

## Preventing Recurrence

[Configuration change or practice that avoids this in the future]

## Need More Help?

[How to contact support]

指南：

• 首先按症状组织内容，因为这正是客户搜索的内容。
• 优先提供最可能的修复方法，再介绍其他方案。
• 始终提供指向支持渠道的“需要更多帮助？”后续选项。
• 如果技术原因很复杂，请用简单的方式向客户解释。

快速解答（FAQ）文章

目标：简洁地回答常见问题。

# [Question in the customer's natural phrasing]

[Direct answer: 1-3 sentences]

## Additional Context

[Deeper explanation, edge cases, or nuance if needed]

## Related Questions

- [Link to related FAQ 1]
- [Link to related FAQ 2]

指南：

• 在第一句话中直接回答问题。
• 如果答案需要分多个步骤讲解，就应归入操作指南文章，而不是 FAQ。
• 为相关 FAQ 添加相互链接，方便客户自行查找相邻问题的答案。

已知问题公告

目标：记录当前存在的 Bug 或限制，以及其当前状态和任何可用的解决方法。

# [Known Issue]: [Brief description]

**Status:** [Investigating / Workaround Available / Fix Underway / Resolved]
**Who is affected:** [Scope]
**Last updated:** [Date]

## What Users Experience

[Description of the observable behavior]

## Workaround

[Step-by-step workaround, or "No workaround is currently available."]

## Resolution Timeline

[Estimated fix date or current engineering status]

## Change Log

- [Date]: [Update summary]

指南：

• 保持状态字段为最新——过时的状态信息会迅速损害信任，程度几乎无出其右。
• 修复发布后立即更新文章，并将其标记为“已解决”。
• 已解决的公告至少保留 30 天，以便仍在搜索旧问题表现的客户能够找到明确答复。

内容生命周期与维护

如果没有积极维护，知识库就会逐渐过时。请遵循以下节奏：

活动	频率	负责人
新文章同行评审	每次发布前	作者 + 主题专家
高流量文章准确性审查	每季度	支持团队
过时内容检测	每月	标记所有 6 个月以上未更新的内容
已知问题状态更新	每周	更新所有未关闭的公告
效果审查	每月	检查有用性评分、跳出率和搜索点击率
覆盖缺口分析	每季度	找出缺少对应知识库文章的主要工单问题

文章状态

1. 草稿：已撰写，等待审查
2. 已发布：已发布，客户可以访问
3. 已标记：因产品变更、用户反馈或内容过时而标记为需要修订
4. 已归档：已从客户视图中移除，但保留在内部供参考
5. 已删除：已从知识库中永久移除

更新还是新建：决策框架

在以下情况下修订现有文章：

• 产品更新改变了操作步骤，但主题相同
• 文章整体合理，但缺少一项细节
• 客户反馈指出某个部分令人困惑
• 发现了更好的解决方法或方案

在以下情况下撰写新文章：

• 新功能或产品领域尚无文档
• 已关闭的工单揭示了完全没有知识库内容覆盖的主题
• 现有文章变得过于冗长，应该拆分
• 不同受众需要以不同方式呈现相同信息

分类体系与交叉链接

建议的分类层级

根据客户的导航方式组织知识库，而非根据组织架构：

Getting Started
  Account creation and setup
  Initial configuration
  Quickstart walkthroughs

Product Capabilities
  [Capability area A]
  [Capability area B]
  [Capability area C]

Integrations
  [Integration A]
  [Integration B]
  API reference

Problem Solving
  Frequent errors
  Performance and reliability
  Active known issues

Billing and Account Management
  Plans and pricing
  Payment and invoicing
  Account settings

交叉链接原则

• 诊断类指向操作类：“有关设置说明，请参阅[如何配置 X]。”
• 操作类指向诊断类：“遇到错误？请参阅[排查 X]。”
• FAQ 指向深入文章：“有关完整操作指南，请参阅[X 指南]。”
• 公告指向解决方法：尽量减少从识别问题到解决问题所需的点击次数。
• 优先使用相对链接：与绝对 URL 相比，相对链接更能经受目录结构调整。
• 避免无必要的循环链接：A 链接到 B，B 又链接回 A，只有在两者都是真正的入口时才合理。

指导原则

1. 面向正在焦急地搜索答案的客户撰写——直接、具体，并立即提供帮助。
2. 每篇文章都必须能通过真实客户会输入的词语找到。
3. 验证内容：亲自按照步骤操作，或请不熟悉该主题的人尝试。
4. 保持聚焦：每篇文章解决一个问题。范围开始扩大时，就拆分文章。
5. 积极维护内容：过时的文章比缺少文章危害更大。
6. 追踪内容缺口：每个原本可以通过文章避免的工单，都是一个内容改进机会。
7. 衡量成效：流量低、评分差或无法减少工单的文章需要重做或退役。