documentation-strategy

文档策略

确定要记录什么、放在哪里、由谁负责，以及如何保持内容更新。与技术栈无关。适用于内部团队文档、产品文档、运行手册、README 和知识库。

---

适用场景

• 为新团队或新产品搭建文档体系
• 审核现有文档
• 整理过时或分散的文档
• 选择文档工具或平台
• 明确要记录和不需要记录的内容
• 制定维护周期
• 确定技术写作工作的范围
• 设计入职文档（与 team-onboarding-playbook 配合使用）

不适用场景

• 撰写单份文档的实际内容（使用 content-and-copy）
• 面向客户的知识库文案（使用 content-strategy）
• 代码注释和内联文档（由 code-review-web 涵盖）
• 一次性的博客文章或其他文章（使用 content-and-copy）

---

必要输入

• 受众（内部、外部、客户、开发人员、高管）
• 现有文档及其状态（位置、形式、最近更新时间）
• 团队规模和发展趋势
• 会产生文档的工作类型（工程、产品、运营、支持）
• 当前使用的工具

---

框架：文档的 4 种类别

不同类别的文档用途各异。混淆它们会导致文档质量变差。

类别 1：参考资料

说明事物是什么。需要时查阅。

示例：API 参考、配置选项、术语表、架构图、联系人名单、决策日志条目。

特征：

• 内容全面
• 经过事实核查，并保持准确
• 可搜索
• 结构稳定（链接不会失效）
• 适用时注明版本

类别 2：操作指南

说明如何完成特定任务。以流程为导向。

示例：“部署到预发布环境”“重置密码”“让新承包商入职”“执行备份恢复演练”。

特征：

• 分步说明
• 由未参与撰写的人测试
• 包含前置条件
• 包含故障排查说明
• 与所记录的系统版本保持一致

类别 3：解释说明

说明事物为何如此。以概念为导向。

示例：架构设计依据、设计决策记录（ADR）、策略文档、愿景文档。

特征：

• 以叙述为主
• 记录背景（原因）
• 通常具有历史性（说明我们为何这样构建）
• 链接到佐证材料

类别 4：教程

以学习为导向，带领读者从零开始掌握技能。

示例：“快速了解我们的代码库”“你的首次部署”、入职学习路径。

特征：

• 按从简单到复杂的顺序编排
• 注重实践
• 不预设读者具备相关范围内的先验知识
• 有明确的完成标准

（这四分法就是 Diátaxis 框架，在技术写作领域广为人知。请牢记。）

---

框架：文档的 5 个层级

不同文档面向不同受众，承担的责任也不同。

层级 1：面向客户

公开文档、客户知识库、API 参考。曝光度高，变更较慢。

标准：

• 编辑审核
• 版本控制
• 明确的负责人
• 严格的时效性要求
• 与版本发布挂钩

层级 2：跨团队／共享

供多个团队使用的文档：共享 API、公共服务、公司级流程。

标准：

• 明确跨团队负责人
• 变更时必须更新
• 中高时效性要求

层级 3：团队内部

由所属团队使用的文档：团队工作方式、运行手册、决策记录。

标准：

• 由团队负责并维护
• 中等时效性要求
• 对下一位加入团队的人有用

层级 4：个人草稿

笔记、草稿、进行中的工作。并非供他人使用。

标准：

• 维护要求低
• 不要从正式文档链接到此类内容
• 有价值时提升到更高层级

层级 5：自动生成

从代码派生的文档：根据注释、架构描述等生成的 API 参考。

标准：

• 自动生成，并在 CI 中运行
• 单一事实来源（代码）
• 审核易用性，而非时效性（时效性由自动化保障）

分层很重要，因为不同层级的维护标准各不相同。要求团队内部文档达到面向客户的标准，既浪费精力，也难以持续。

---

工作流

步骤 1：审查现状

• 有哪些文档？
• 它们在哪里？（通常分散在各处）
• 每份文档由谁负责？
• 内容有多新？
• 人们真的会用它们吗？（如果可以衡量，就查看页面浏览量或引荐来源）

审查结果往往令人惊讶。大多数团队拥有的文档比他们意识到的更多，分布的位置也比他们意识到的更多。

步骤 2：分类并分级

针对每份文档：

• 类别（参考 / 操作指南 / 说明 / 教程）
• 层级（客户 / 共享 / 团队 / 草稿 / 自动生成）

有些文档包含多种类型。标注其主要类别。

步骤 3：找出缺口

团队需要哪些现有文档尚未涵盖的内容？

常见缺口：

• 没人能回答“X 到底是如何运作的？”
• 最近没人负责入职培训的岗位缺少入职指南
• 从未出过故障的系统缺少运行手册（至少目前还没有）
• 缺少“为什么要这样做”的决策依据

询问大家希望哪些内容有文档记录。他们最清楚。

步骤 4：清理冗余内容

这类文档包括：

• 内容过时且无人更新
• 多处重复（应指定一份为权威版本，其余版本应重定向或删除）
• 关于已不存在事物的文档
• 长期搁置的草稿

删除或归档。过时的文档比缺少文档更糟（人们可能会相信它们）。

步骤 5：确定存放位置

文档的存放位置会影响它们是否得到维护。

常见位置：

• 代码仓库（markdown）： 适用于与代码紧密相关的文档（README、ADR、服务运行手册）
• Wiki / Notion / Confluence： 适用于跨团队和团队内部文档
• 文档站点（Docusaurus、Mintlify、自定义站点）： 适用于面向客户的文档
• 工单 / 决策日志： 适用于临时记录

不要追求只有一个存放位置，而要确保能清楚回答“这类文档应该放在哪里？”

步骤 6：明确负责人

每份文档都要有负责人。没有负责人，文档就会过时。

负责人可以是：

• 一个团队
• 一个岗位（值班轮班组、PM、EM）
• 一个人，并指定备份负责人

如果负责人不明确，这份文档可能就不值得保留。

步骤 7：确定维护周期

按层级划分：

层级	审查周期
面向客户	每次发布时，以及每季度
跨团队	每季度
团队内部	每季度
个人草稿	无
自动生成	每次变更时

维护工作包括：

• 核实准确性
• 根据系统变更更新文档
• 归档不再相关的内容
• 处理用户反馈

步骤 8：将文档更新纳入工作

文档工作不是一个独立项目，而是产出文档的工作本身的一部分。

• 新功能：文档是功能的一部分
• 新流程：文档是上线工作的一部分
• 做出决策：提交 ADR 或决策日志条目
• Bug 复盘：更新运行手册
• 新员工入职：根据其体验更新入职文档

只发布功能、不编写文档的团队，实际拥有的东西比他们以为的少。

步骤 9：让文档易于发现

再好的文档，如果没人找到，也毫无用处。

• 确实有效的搜索（大多数平台都有，效果各不相同）
• 主要主题的索引页面
• 相关文档之间的交叉链接
• 常见替代表述的搜索别名
• 将最常用的文档置顶

步骤 10：衡量

可衡量的指标取决于平台：

• 页面浏览量
• 搜索查询（以及无结果的查询）
• “这有帮助吗？”反馈
• 页面停留时间
• 引荐模式

对于内部文档，定性指标往往更有用：同样的问题是否一再被问起？如果是，说明文档没有发挥作用（可能是文档不存在、没人找到，或内容不清楚）。

---

具体模式

每个项目都要有 README

每个代码仓库都有一份 README，回答以下问题：

• 这是什么？
• 如何运行？
• 如何参与贡献？
• 如何查找更多信息？

每个问题通常用五句话就够了。长度不是目标，兑现“读我”这个承诺才是。

ADR（架构决策记录）

针对每个重要决策：

# ADR-NNN: [Title]

Status: [Proposed / Accepted / Deprecated / Superseded]
Date: [Date]

## Context
[What's the situation? What forces are at play?]

## Decision
[What was decided?]

## Consequences
[What happens because of this decision? Both good and bad.]

ADR 会不断积累，最终成为解释“为什么要这样做”的文档层。

运行手册

按系统列出：

• 系统是什么
• 如何访问
• 常见操作（附命令）
• 常见故障模式
• 从备份恢复的流程
• 升级联系人的联系方式

运行手册标准请参阅 incident-response 和 backup-and-disaster-recovery。

入职路径

按角色列出：

• 第 1 天
• 第 1 周
• 第 1 个月
• 90 天

请参阅 team-onboarding-playbook。

决策日志

轻量版 ADR。记录日期、决策、决策者及原因。无需繁琐流程，也能留存记录。

术语表

收录团队或产品中特有含义的术语，减少混淆，也能帮助 AI 工具学习（稍后详述）。

---

工具

工具本身不如规范的执行方式重要。话虽如此：

工具类别	示例	适用场景
Wiki	Notion、Confluence、GitBook	跨团队、内部使用
代码中的 Markdown	GitHub、GitLab、Bitbucket	README、ADR、技术文档
文档站点	Docusaurus、Mintlify、ReadMe	面向客户的公开文档
内部站点	MkDocs、自定义站点	团队专用规范

注意事项：

• 搜索质量（搜索效果差会让一切更糟）
• 编辑器质量（没人愿意在难用的编辑器里写作）
• 版本控制（能否查看历史记录？）
• 权限（合适的人能够读写）
• API 和集成（用于自动化）
• 与团队规模相匹配的成本

小团队使用单一 Wiki 工具就足够了。较大的团队则可采用分层工具。

---

AI 相关说明

大模型和 AI 助手越来越常读取文档。需考虑以下几点：

• 清晰、一致的结构对人和 AI 都有帮助
• 术语表对人和 AI 都有帮助
• 文件级元数据（front matter）对工具有帮助
• AI 爬虫可能会读取公开文档；如有需要，可考虑使用 llms.txt
• AI 生成的草稿只是起点，并非最终答案；需要由人审核

---

常见失败模式

把文档当作“以后再做”的任务。 总是留到以后写。所谓以后就是永远不写。把文档纳入工作流程。

所有内容都塞进一份超长文档。 Wiki 页面长达 8,000 词，没人会读。按类别和主题拆分。

过时且无人信任的文档。 “可能已经过时”这种想法会扼杀文档。要么保持更新，要么归档。

人人都认同应该有，却没人动笔的文档。 团队都认同入职文档很有价值。几个月过去了，仍然没人写。明确指定负责人。

沦为坟场的 Wiki。 页面很多，却没有人信任其中任何一页。审查并归档，然后用一套更精简的内容重新开始。

文档与代码分离。 API 文档放在 Wiki，代码放在代码库，两者逐渐脱节。将它们放在一起。

缺少示例的文档。 没有示例的参考资料很难使用。示例能让内容更具体。

无法运行的示例。 代码示例曾经可用，后来逐渐失效。尽可能在 CI 中测试示例。

本可用参考资料解决，却写成长篇文档。 用 2,000 词解释本可用一张 30 行表格说明的内容。选择合适的形式。

多个事实来源。 同一信息出现在三个地方，内容略有不同。选定一个权威来源，并将其他来源重定向到它。

没人使用的文档工具。 因为某项功能而采用，但团队实际上并不使用。选择团队愿意使用的工具。

比文档还长的文档风格指南。 流程喧宾夺主。指南应简短。

没有标记文档已弃用的方式。 旧文档与当前文档并列，却没有任何标记。添加“已弃用”或“已归档”状态。

没有分析数据。 不知道哪些内容有人使用，也不知道还缺少什么。即使是基础的页面浏览量数据，也能帮助确定优先级。

读起来像规范说明的文档。 内容密集、正式，难以快速浏览。要以读者为中心来写。

---

输出格式

文档策略应包含：

• 审查： 现有内容、所在位置及其状态
• 分级与分类： 应用于现有文档的框架
• 差距清单： 应有但尚不存在的内容
• 工具决策： 各类文档的存放位置
• 负责人映射： 各项内容的负责人
• 维护周期： 各项内容的审查时间
• 风格指南（简要）： 一致性标准
• 路线图： 按优先级安排填补差距及清理冗余内容的工作

---

参考文件

• references/doc-types-guide.md：关于四种文档类型（参考、操作指南、说明、教程）的详细指南，包含每种类型的示例和模板。