文档不是写完就结束的产物,而是一项需要持续维护的工程。很多团队在项目初期热情高涨地写文档,几个月后却发现内容过期、结构混乱、无人更新。OTTO 文档写作规范的核心思路,是把文档当作代码来对待:有明确的写作标准、有可执行的维护流程、有清晰的责任归属。本文从写作规范和维护习惯两个方面展开,给出一套可以直接落地的做法。
一、写作规范:让文档有章可循

1. 先定结构,再填内容
写文档最容易犯的错误是边想边写,结果结构松散、重点模糊。OTTO 规范要求每篇文档动笔前先列出一个三级以内的标题骨架,明确读者是谁、读完要解决什么问题。骨架确认后再填充内容,通常能减少一半以上的返工。
结构上建议遵循「总—分—总」的节奏:开头一段说明文档目的和适用场景,中间按逻辑层次展开,结尾给出总结或下一步行动指引。读者即使只读开头和结尾,也能获得核心信息。
2. 标题层级控制在三层以内
层级过深会让读者迷失位置。Otto 规范建议正文标题最多到三级:一级标题划分大块,二级标题组织小节,三级标题细化要点。如果发现需要四级标题,往往说明内容应该拆分成独立文档,而不是继续往下嵌套。
3. 一段只讲一件事
段落是阅读的基本单位。每段控制在三到五句话,只表达一个核心意思。段落过长时,读者容易跳读;段落过短时,信息又显得碎片化。判断标准很简单:如果一段话里出现了两个以上并列的重点,就该拆成两段。
4. 用具体代替抽象
「系统性能良好」「流程较为规范」这类表述几乎没有信息量。规范要求尽量用可验证的具体描述替代模糊形容词,比如「接口平均响应时间控制在 200 毫秒以内」「需求变更需在每周例会上评审」。具体化不仅让文档更可信,也让后续维护时有明确的核对依据。
5. 术语和格式统一
同一概念在全文中保持同一叫法,不要一会儿叫「用户中心」、一会儿叫「账户模块」。数字、日期、单位、标点也应统一格式。建议团队维护一份小型术语表,放在文档库首页,新成员写作前先对照一遍,能显著减少沟通成本。
二、维护习惯:让文档保持鲜活
1. 文档与变更同步
文档过期的根源,是变更发生时没人想起文档。Otto 的做法是把文档更新写进变更流程:任何影响功能、流程或接口的改动,在合并代码或发布版本时,必须同步检查相关文档是否需要更新。把「更新文档」作为完成定义的一部分,而不是事后补课。
2. 设置文档负责人
没有归属的文档等于没有文档。每篇文档应明确一位负责人,负责内容的准确性和更新节奏。负责人不必亲自写所有内容,但要确保有人写、有人审、过期有人改。人员变动时,负责人交接要作为离职流程的固定环节。
3. 定期巡检与清理
建议每季度做一次文档巡检,重点检查三类问题:内容是否与现状一致、链接是否失效、结构是否仍然合理。对长期无人访问、内容已无参考价值的文档,果断归档或删除。文档库的价值在于精而不在于多,冗余内容只会增加检索成本。
4. 建立轻量评审机制
重要文档发布前应经过至少一位同事评审,重点看结构是否清晰、表述是否有歧义、关键信息是否遗漏。评审不必追求完美,控制在半小时以内即可。轻量评审的好处是可持续,过重的流程反而会让人回避写文档。
5. 记录修改而非覆盖
对于规范类、流程类文档,建议在文末保留简短的修订记录,注明修改日期和主要变化。这样读者能判断内容的新旧程度,维护者也能追溯历史决策。修订记录控制在几行以内,不需要写成完整的变更日志。
三、结语

文档规范解决的是「怎么写」的问题,维护习惯解决的是「怎么活下去」的问题,两者缺一不可。落地时不必追求一步到位,可以先从统一标题层级和设置文档负责人这两件小事做起,再逐步引入变更同步和定期巡检。规范的价值不在于条文本身,而在于团队是否真的按它执行。坚持三个月,文档质量的变化会肉眼可见。















暂无评论内容