解决问题后,只保存一条命令或者一段代码,确实很方便。但时间一长,容易忘记它适用于什么环境、运行之前有什么条件、是否会带来其他影响。留下一点判断过程,能让笔记更耐用。
先说明当时在做什么
用两三句话交代背景:准备完成什么任务、使用什么环境、遇到了什么现象。涉及软件版本时,可以记录关键版本;与问题无关的环境信息则不必全部罗列。
标题最好能描述具体问题。与“今天的踩坑记录”相比,“本地页面能打开,部署后样式丢失”更容易被搜索到,也更容易判断是否与当前问题相关。
把结论和推测分开
记录哪些是已经观察到的事实,哪些只是尚未验证的判断。例如,“浏览器请求样式文件时返回未找到”是现象;“可能是上传目录不完整”是推测。两者分开,能避免把一次猜测当成通用结论。
可以重复使用的记录结构
- 背景:当时想完成什么。
- 现象:预期与实际结果有什么差别。
- 判断:检查了哪些信息,排除了哪些原因。
- 处理:最终调整了什么,以及调整的理由。
- 验证:如何确认问题已解决,还有哪些限制。
留下真正影响结果的步骤
不必把所有尝试都写成流水账。保留关键检查、有效修改和必要的前置条件。如果一个失败尝试能够解释常见误区,也可以用一句话说明它为什么无效。
对于可能改变文件或配置的操作,应记下涉及的范围、原状态和恢复方法。这样,下次照着笔记操作时,能够先判断是否适合当前环境。
注明适用范围,允许后来修正
一次成功不代表所有情况都成立。如果只在本地环境验证过,就明确写出验证范围;如果借鉴了外部资料,可以附上原始来源,方便后来查阅更新。
当软件版本或使用方式改变后,旧笔记可能需要补充。可以在原文添加修订说明,解释新的条件和结论,而不是让前后的描述互相矛盾。
一篇有用的笔记,不必面面俱到。它只需要让下一次遇到问题的自己,知道从哪里开始,怎样确认,以及何时停下来重新判断。