1 / 4概念
Docs & Knowledge Management
文档不是代码的附属品,而是团队对"为什么这样写"的唯一可检索记录。本页只讨论三件事:写什么、放在哪里、什么时候会过期。
1 概念
| 类型 | 回答的问题 | 例子 |
|---|---|---|
| 教程 | 第一次怎么做 | 跑起一个包 |
| 操作指南 | 特定任务怎么做 | 发布一个版本 |
| 参考 | 字段与参数的准确定义 | 元数据契约 |
| 解释 | 为什么这样设计 | 分类架构 |
四种类型不要混在一页:读者带着不同问题来,混写会让两类人都找不到答案。
2 机制
- 内容进 Git,与代码同一个评审流程。
- 路径就是分类:一个文档只有一个物理归属。
- 交叉关系放 frontmatter(
requires/next/related),不要再建第二个目录。
3 实践
- 页面开头一句话说明它回答什么问题。
- 枚举完整,不用"例如"代替列表。
- 写明失败边界,而不只是规则。
- 交叉引用用 key,不用手写 URL。
4 边界
每页都有 status、owner 与 updated。stable 页面带 review_by,过期先警告再失败。没有新鲜度机制的文档库,三个月后就会变成考古现场。