核心要点
面向读者：先想清楚"谁会看、想解决什么问题"，按使用者的目标组织内容，而非堆砌实现细节
分清类型：README（快速上手）、架构决策记录 ADR（为什么这样选）、API 文档（怎么调）、runbook（出问题怎么处理）各司其职
讲清"为什么 + 怎么用"：代码能说清"是什么"，文档要补上动机、取舍和使用方式，并优先给可运行示例
可维护：文档靠近代码、随代码一起评审更新，宁可少而准，避免一堆没人维护的过时文档
标准回答
面向读者，而非面向作者
好文档从读者出发：明确目标读者（新同事？调用方？值班工程师？）和他们要完成的任务，按使用场景而非代码结构来组织。问自己"读者读完能不能动手做事"。
按类型各司其职
不同文档解决不同问题：README 让人快速跑起来；架构决策记录（ADR）记录"为什么这样选、否决了什么方案"；API 文档讲清入参出参、错误与示例；runbook 给值班同学"出故障如何排查与恢复"的步骤。混在一起反而都讲不清。
讲"为什么"，并保持可维护
代码本身能表达"做了什么"，文档真正的价值是解释"为什么这么做、有何取舍、该怎么用"，并优先放可复制运行的示例。把文档放在代码仓库里、随代码评审一起更新，过时即修；宁可精炼准确，也不要大量没人维护的陈旧文档误导人。
常见误区
⚠️ 常见踩坑
写一大堆事无巨细、却很快过时没人维护的文档，或只记"做了什么"而不写"为什么"。结果是文档和代码脱节、误导读者。应面向读者、靠近代码、随代码更新，重点解释动机与用法。
追问
追问 1：什么是 ADR（架构决策记录），为什么有用？
ADR 是一份简短文档，记录某个重要技术决策的背景、考虑过的方案、最终选择及其理由和影响。价值在于把"为什么这么定"留存下来：几个月后回看或新人接手时，不必反复追问历史、也避免重复推翻已论证过的决策。通常一决策一文件、按时间编号，随项目演进追加。
追问 2：怎么防止文档过时？
把文档当代码对待：放进同一仓库、随相关改动一起在 PR 里更新和评审，文档过时视为缺陷。能自动生成的就自动生成（如从代码注释生成 API 文档），示例最好是能跑、能被测试覆盖的。同时控制总量——只维护真正有人读的文档，删掉无人维护的内容比留着误导更好。
延伸学习
与本题相关的知识库文章、术语、工具与行业资讯。