拉卡拉开放平台

官方文档面向所有接入方，必然是通用的；团队需要的却是与自己业务相关的那一部分。把前者转成后者，是一项投入很小、回报很大的工作。

内部说明应该包含什么

踩过的坑最有价值

正确路径文档里有，但「哪种写法会出问题」通常只存在于当事人的记忆里。

把踩过的坑写下来，等于把个人经验变成团队资产。新人读到时省下的时间，往往是写下它的数倍。

结构如何组织

1. 按问题组织，而不是按章节顺序组织；
2. 每节开头先给结论，再给细节；
3. 常见错误单独成节，放在靠前位置。

第一条是关键：大多数人是带着问题来查文档的，按问题组织能让他们更快找到答案。

必须指定维护人

没有维护人的文档，一定会在某次变更后开始失真，最终变成误导。

• 指定一个明确的负责人；
• 每次相关变更后同步更新；
• 定期回顾，确认内容仍与实际一致。

写多少合适

不必追求完整，覆盖本团队实际用到的部分即可。过长的文档反而没人读。

一个实用技巧

在文档里保留一段「最近更新」，记录每次修改的内容与时间。这既方便读者判断是否需要重看，也能反映文档是否还活着。

从文档到检查清单

文档里最实用的部分，往往可以进一步压缩成一份检查清单：上线前逐项打勾，排查时逐项对照。清单比文档更容易被真正用起来。

写给谁看

动笔之前先想清楚读者是谁，这决定了写什么、怎么写。

一份文档很难同时满足所有人，可以按读者拆成几份，每份都保持简短。

示例比描述有用

与其用文字描述参数怎么填，不如直接给一个能跑的示例。示例应当是真实的、经过验证的，而不是随手编的。

把不确定标出来

文档里如果有不确定的内容，应当明确标注，而不是含糊带过。一份标注了不确定之处的文档，比一份看似什么都确定、实则错误百出的文档有用得多。

文档也要有版本

记录文档的适用版本与时间，让读者知道这份说明对应的是哪个状态的系统。缺少版本信息的文档，在系统变更之后会变成误导。

写文档这件事，最大的受益者往往不是别人，而是未来的自己。今天记录下的每一个坑，都是明天省下的时间。

文档写作有一个朴素的标准：写完三个月后自己再读一遍，如果还能看懂并且有用，就是合格的。做不到这一点，说明它写得太依赖当时的上下文了，需要补上背景说明与具体示例。

此外，文档里如果能附上几个真实踩坑案例，说服力会比任何说明都强。

最后一点：文档不需要一次写完。先把最常问的几个问题写清楚，之后再逐步补充，比追求一次成型要现实得多。

一份能被反复查阅的文档，胜过十份写得很完整却没人打开的文档。让文档被使用，比让文档变完美更重要，这也是判断文档是否值得继续投入的直接标准。

换句话说，衡量文档价值的标准不是厚度，而是被打开的次数。

把这份判断标准记在心里，写文档时就更容易取舍：宁可少写一点，也要让写下来的部分真正被用上。

文档如此，其他沉淀工作亦是如此。