「发布收成一条命令」。
原来要记四步。现在一条。失败会停,不会继续往下。
记录里保留失败的那一次。只写成功,别人学不到边界。失败时的输出、当时的配置、本来期望发生什么,三样放在一起。修好之后补一句:如果再出现,先看哪一行。没有这句,这篇就只是故事。
展示的是一个能用的小东西,不是计划。写清楚它解决哪一件具体的事,输入是什么,输出是什么,什么情况下不要用。边界没做完就直说。主路径通了就可以给别人试,不必等所有边角都齐。
这次按时间写。先发生什么,中间查了什么,最后留下什么。不把后来才知道的结论写成一开始就想到了。查的时候把猜的和已经验证的分开,避免第二天把猜测当成事实。验证用的是改之前的同一条路径,不是换一组更容易过的输入。
复查「发布收成一条命令」时按这四步,不靠感觉。用改之前的同一组输入再走一遍,结果要变成预期的那样。在日志里打出实际读到的配置名、端口或库名,确认不是另一个还没关的进程。换一个干净环境再做一次。最后把现象、改动、确认方法写成三行放进仓库。
补充记录。展示写给会用的人,不写给围观的人。第一段说明它解决的一件事。第二段写输入和输出,最好有一条最小例子。第三段写不要在什么情况下用,例如数据太大、需要外网、还没做的边界。主路径通了就可以给别人试,边角列在后面,不要等全部做完。错误提示写下一件事,而不只写代号。仓库里放怎么跑、怎么停。停不掉的小工具,不该算做完。
操作顺序。1. 用一段话说明它解决的一件事。2. 给出最小输入和对应输出。3. 写明不要在什么情况下用。4. 写怎么启动、怎么停、失败时看哪。5. 主路径通了就让别人试,没做的边界列在后面。6. 错误提示写成下一件事,而不是只给代号。7. 自己按说明从干净环境走一遍。走不通就改说明。展示的标准不是功能多,而是另一个人能在不问作者的情况下用起来并停掉。