本文是「学习方法与效率」系列第 7 篇，20 个问题讲清文档沉淀与知识分享，覆盖结构、更新、检索、复用和团队传播。可按目录跳读。
Q1. 为什么要写文档？
文档是把个人经验变成团队资产的方式。人走了、时间久了，口口相传的信息会丢失，文档还在。
文档能降低沟通成本、减少重复踩坑、支持新人上手和故障排查。它也是设计质量和思考深度的体现。
项目里我会把关键决策、接口、排障和复盘写下来。文档不是额外工作，是工程的一部分。能把方案写清楚，说明真的想清楚了，写不清楚往往也没想清楚。文档还能降低对个人的依赖，团队轮岗和交接时不至于从零开始，新人也能自己查。
Q2. 文档分哪些类型？
常见有设计文档、接口文档、README、ADR、排障手册、复盘报告、 runbook 和分享材料。
不同类型目的不同：设计文档讲方案和取舍，接口文档讲契约，README 讲怎么用，ADR 讲为什么这么选。
项目里我会按类型管理，避免一份文档承担所有职责。类型清楚，读者才知道该看哪份，维护也知道该更新哪份。类型不用多，四五种覆盖设计、接口、决策、排障和复盘就够，多了反而没人维护，也找不到入口。
Q3. 怎么判断该写文档？
看信息是否会被重复问、决策是否难回溯、操作是否容易出错、系统是否有多个使用者。
一次性的小事可以不写，但涉及多人协作、长期维护和线上操作的内容要写。
项目里新服务、接口变更、故障处理和重要选型都会写文档。判断标准是：不写会不会有人踩坑。信息会被重复问、决策难回溯、操作易出错，就应该写。不写会不会有人踩坑，是最好的判断标准。同样的解释我说过第二遍，就该写成文档，别靠嘴重复，重复解释是最隐形的成本。
Q4. 怎么写设计文档？
设计文档要写背景、目标、约束、方案、备选、取舍、风险和上线计划。先讲为什么做，再讲怎么做。
方案要画架构图和数据流，写清接口、存储、异常和降级。备选方案要说明为什么没选。
项目里设计文档会在评审前发出来，评审后更新结论。文档要能回答“为什么这样设计”，不只是“做了什么”。背景、目标、约束、方案、备选、取舍、风险和上线计划都要写。备选方案和取舍比最终方案更有信息量，能看出当时的判断。
Q5. 怎么写接口文档？
接口文档要写认证、地址、方法、参数、响应、错误码、限流和版本。示例要能直接跑通。
字段要写类型、必填、范围和默认值。错误码要覆盖常见异常，不能只写成功示例。
项目里接口文档用 OpenAPI 生成，再补业务说明和示例。文档要和代码同步，不能手写一份、代码改一份。字段要写类型、必填、范围和默认值，错误码要覆盖常见异常。文档最好从代码生成，手写很容易过期，过期比没有更危险。变更流程里要加一步文档同步，否则生成也跟不上。
Q6. 怎么写排障和复盘文档？
排障文档要写现象、影响、排查过程、根因、临时措施和最终修复。复盘要写时间线、决策点和改进项。
要区分事实和推测，保留日志、监控和命令。改进项要有 owner 和截止时间。
项目里故障复盘会写清影响范围和用户感知，避免只写技术细节。复盘不是追责，是防止再犯。要区分事实和推测，保留日志、监控和命令，改进项要有 owner 和截止时间。排障文档要能让人按步骤复现和修复，敏感信息要脱敏。复盘报告要公开可查，让其他团队也能吸取教训。
Q7. 怎么写 README？
README 要回答：这是什么、解决什么问题、怎么安装、怎么运行、怎么配置、怎么测试、怎么贡献。
要有最小可运行示例和常见问题。不要一上来讲架构，先让读者跑起来。
项目里新仓库的第一份文档就是 README。README 写不好，别人连试都不想试。README 要回答这是什么、解决什么问题、怎么安装、怎么运行、怎么配置、怎么测试、怎么贡献。要有最小可运行示例和常见问题，先让读者跑起来。
Q8. 怎么写 ADR？
ADR 是架构决策记录，写清背景、决策、备选、后果和状态。它记录“为什么”，不是“怎么做”。
ADR 要短，一页左右。编号管理，状态可以是提议、接受、废弃或替代。
项目里选型、协议变更和重大架构调整都会写 ADR。以后有人问为什么不用另一个方案，直接看 ADR。ADR 要短，一页左右，编号管理，状态可以是提议、接受、废弃或替代。它记录决策上下文，不是操作手册。ADR 要写清被否决的方案和原因，后人才能判断是否要推翻，也能避免重复讨论。
Q9. 文档结构怎么组织？
文档要有清晰的标题、摘要、目录、正文和附录。长文档要分节，节与节之间要有逻辑。
先给结论，再给细节。读者时间有限，要能快速找到重点。
项目里我会用统一模板：背景、目标、方案、风险、结论。模板能降低写作成本，也方便评审。先给结论，再给细节，长文档要分节，读者时间有限。要有摘要、目录、标签和交叉链接，方便搜索和定位。模板固定后，评审只看内容，不用每次讨论结构，写作和评审都会快很多，新人也能照着填。
Q10. 怎么保证文档不过时？
文档要标注版本、最后更新时间和 owner。变更代码时同步更新文档，评审时检查。
关键文档要定期巡检，过时内容要标注或归档。没有人维护的文档，很快就不能信。
项目里接口文档从代码生成，设计文档随版本更新。文档过期比没有更危险。要定期巡检，过时内容标注或归档，关键文档要有 owner。最好和代码放在一起，变更时一起评审，没有人维护的文档很快不能信。过期内容宁可删掉，也不要留着误导人，删之前确认没有被其他文档引用。
Q11. 怎么做文档评审？
评审要看结构、事实、逻辑、风险和可执行性。不要只挑错别字。
评审人要能看懂，能按文档操作。关键决策要有依据，关键步骤要有验证。
项目里设计文档和 runbook 会评审，接口文档靠工具校验。评审意见要闭环，不能提了不改。评审看结构、事实、逻辑、风险和可执行性，评审人要能按文档操作。关键步骤要验证，评审意见要闭环，不能提了不改。评审记录要留档，谁提的、改没改、为什么没改，都要能追溯，否则评审就是走过场。
Q12. 怎么做知识分享？
分享要围绕听众的问题，不要自嗨讲技术细节。先讲为什么、能解决什么，再讲怎么做。
要有案例、Demo 和踩坑，让听众能带走东西。时间控制在半小时到一小时，留提问。
项目里分享前会收集问题，分享后发材料和回放。分享不是表演，是让别人少走弯路。要有案例、Demo 和踩坑，时间控制在半小时到一小时，留提问。分享后发材料和回放，让没来的人也能看懂。分享要控制信息密度，一页一个观点，别把二十页塞进半小时，听众记不住。
Q13. 怎么做技术分享的选题？
选题来自真实问题、近期踩坑、新技术验证和团队共性需求。不要选太泛或太窄的题。
要看听众是谁：新人需要入门，资深需要深度，业务需要结果。选题要匹配。
项目里我会选“最近解决的问题”和“大家都会遇到但没时间研究的问题”。真实问题最有共鸣。选题要小、具体、有案例、有结论、有行动，能讨论也能复用。要匹配听众：新人需要入门，资深需要深度，业务需要结果。选题宁小勿大，一个具体问题讲透，比泛泛介绍一个领域更有用，也更容易准备。
Q14. 怎么把分享变成可复用资产？
分享后要整理成文档、代码示例、检查清单或视频。材料要能独立阅读，不依赖现场。
要标注版本、适用场景和局限。后续有人问，可以直接发材料。
项目里分享材料会进知识库，和项目文档关联。一次分享，多次复用，才划算。材料要标版本、适用场景和局限，能独立阅读，不依赖现场。要进知识库、建索引、能更新，方便别人直接复用。材料要有人维护，代码示例要能跑通，否则半年后就变成过时文档，反而误导人。
Q15. 怎么建立团队知识库？
知识库要有分类、搜索、权限和 owner。内容要覆盖新人指南、项目文档、排障手册和最佳实践。
要有统一的命名和模板，避免重复和碎片化。定期清理过时内容。
项目里知识库按主题和项目组织，重要文档有 owner。知识库不是网盘，要能被找到和使用。要有分类、搜索、权限和 owner，内容覆盖新人指南、项目文档、排障手册和最佳实践。要有统一模板和命名，避免重复和碎片化。知识库要有入口页，新人第一天就知道去哪找什么，不用挨个问人。
Q16. 怎么让文档可搜索？
标题和正文要用读者会搜的词，标签要统一。避免用内部黑话和缩写。
文档要有摘要和关键词，方便搜索命中。目录和交叉链接能帮助定位。
项目里我会用统一标签：项目、技术栈、问题类型。搜索不到，等于没有。标题和正文要用读者会搜的词，文档要有摘要和关键词，目录和交叉链接帮助定位。要避免内部黑话和缩写，搜索不到等于没有。标题要写具体问题，不要只写模块名，搜索时才容易命中，摘要里也要放关键词。
Q17. 怎么处理敏感信息？
文档不能写密钥、密码、内网地址、手机号和真实用户数据。示例要脱敏，截图要打码。
敏感文档要控权限、加密和审计。对外分享前要审核。
项目里医疗和支付相关文档会做脱敏，访问按角色控制。文档泄露也是安全事故。不能写密钥、密码、内网地址、手机号和真实用户数据，示例脱敏，截图打码。敏感文档要控权限、加密和审计，对外分享前要审核。权限要定期复核，人员变动后及时回收，离职交接时也要检查，避免留下后门。
Q18. 怎么衡量文档价值？
看使用量、搜索命中、新人上手时间、重复问题减少和故障处理速度。不能只看文档数量。
文档价值是间接的，但可以通过案例和反馈体现。没人看的文档就是成本。
项目里我会看文档的访问和引用，定期清理低价值内容。价值不在多，在有用。使用量、搜索命中、新人上手时间、重复问题减少和故障处理速度都是指标。还要看引用、反馈、维护成本和复用次数。低价值文档要合并或删除，数量多不代表沉淀好，没人用的文档就是维护负担。
Q19. 怎么培养写文档的习惯？
把文档纳入 Definition of Done，代码合并前必须更新文档。模板和工具要简单，降低写作门槛。
从小文档开始，比如一次排障记录、一个接口说明。写完有人用，就有正向反馈。
项目里我会先写一页纸，不追求完美。持续写，比一次写很长的文档更有效。把文档纳入 Definition of Done，代码合并前必须更新文档，模板和工具要简单。从小文档开始，写完有人用，就有正向反馈。团队要把写文档算进工作量，不然永远是下班后补。
Q20. 项目里怎么实践文档沉淀？
项目里设计、接口、排障、复盘和 runbook 都要有文档。关键文档有 owner、版本和评审。
LingShu 的 RAG 管线、SuGuangMall 的秒杀链路和 FlavorDash 的 AI 模块，我都会写清架构、接口和故障处理。
文档沉淀不是额外负担，是让项目可维护、可交接、可复盘。写得清楚，团队才跑得快。设计、接口、排障、复盘和 runbook 都要有文档，关键文档有 owner、版本和评审。写清架构、接口和故障处理，项目才可交接。