脉穗成长计划
技术文档的“考古价值”你接手一个老系统，翻文档发现三年前写了一句话“这里有个坑，别踩”。但没写是什么坑。你很崩溃，但又不敢删。这就是文档的“考古价值”没发挥好——写文档的人只记录了“有坑”，没记录坑的“坐标”和“深度”。好的技术文档应该像考古报告：不是告诉你“这里有文物”，而是告诉你“在哪个地层、哪个探方、挖到什么、怎么挖出来的”。具体来说，写坑的时候要写清楚：现象是什么（比如每个月1号凌晨CPU飙到100%），根因是什么（定时任务和日志归档时间重叠），解法是什么（把定时任务改到2点），以及最重要的——你怎么发现这个问题的（看了哪个日志、跑了哪个命令）。这样写，三百年后另一个程序员接手，他不只是知道了“有个坑”，他还学会了“怎么找这种类型的坑”。你写文档的十分钟，可能救未来某个人的一天。这笔账，怎么算都值。
发布于 广东
分享
评论
赞
未登录
友善发言
评论
加载中
