只保留必要的几类文档
文档不是越多越好。团队通常只需要几类：项目背景与目标、环境与部署说明、接口与数据约定、关键决策记录、常见问题处理。能覆盖高频问题的少量文档，比无人维护的文档库更有价值。
判断一份文档是否值得写，可以看它是否会被重复查阅。只讲一次的内容，口头说明即可；会被反复问到的问题，才需要沉淀，否则写作成本会远高于收益。判断标准应当由使用者决定，而不是由写作者决定。
每类文档都要有明确的读者和使用场景。写给新人看的和写给排障时看的，组织方式完全不同，混在一起会导致两边都不好用，最后谁也不愿意打开。
写文档之前先想清楚它是给谁、在什么场景下用的。如果连这两个问题都答不上来，通常说明这份文档暂时不必写，或者只需要留一段简短说明。
位置统一比格式精美重要
文档最容易失效的原因是位置分散，一部分在聊天记录，一部分在个人笔记，一部分在代码注释里。与其统一格式，不如先统一入口。找不到的文档等于不存在。
入口最好离工作场景足够近，例如代码仓库根目录的说明文件，或者团队常用的协作空间首页。让查阅成为顺手动作，而不是额外步骤。入口藏在超过两层的目录里，往往就没人愿意点了。入口一旦确定就不要频繁更换，每换一次都会流失一部分使用习惯，重新培养的成本比想象中高。
文档内部也不必追求长文。结构清晰、结论在前、步骤可照做，通常比完整叙述更实用，尤其是在排障场景下，读者需要的是能立刻执行的下一步。
维护责任要落到人
没有责任人的文档会自然过期。可以为每份文档指定一名维护者，负责在相关流程变化后更新内容。责任到人不是增加负担，而是避免所有人都以为别人会更新。
同时约定触发更新的时机，例如部署流程调整、接口变更、新成员反复提问。把更新动作挂在已有事件上，比要求定期检查更容易执行，也不容易遗漏。
对于明显过期的内容，宁可直接删除或标注失效，也不要留在原处误导他人。保留错误信息的危害大于信息缺失，尤其在排障时，错误步骤会让人离答案越来越远。
让文档进入日常工作流
文档要真正起作用，需要被放进已有流程，而不是作为额外任务。例如提交改动时同步更新接口说明，新成员入职时按上手文档走一遍并反馈问题。流程中自然产生的文档，才容易被持续维护。
评审也可以把文档影响纳入检查，判断这次改动是否让某份说明失效。这类检查成本很低，却能显著延长文档的有效期。
最后，鼓励使用者在文档里直接补充。让使用者成为共同维护者，比依赖少数人集中整理更可持续，也更容易让内容贴近真实使用场景。
