《把回归文件写进说明里:接手的人先跑一遍就知道工具状态》
回归清单存成文件之后,我做的下一步,是把这份文件写进小工具的说明里。文件只解决了一个人的问题:我自己知道去哪找、怎么跑。但小工具早晚要给别人看——可能是隔了两个月回来的我,已经忘了当时为什么这样写;也可能是第一次打开它的接手人,根本不知道它现在是好是坏。文件放在角落里不说话,说明就是让它开口的地方。
我的说明只有一页,分成三段,写的都是接手的人第一天最需要知道的事。第一段一句话,说清楚这个工具是干什么的:帮小商家把顾客留言分好类,再按商家的口吻生成一句回复草稿。没有功能列表,没有技术名词,只说它解决什么问题、给谁用。第二段写怎么跑:先打开回归文件,照着里面的五组输入一组一组跑,跑完对照文件里的期望答案。第三段写怎么判断:五组里哪几组必须全对、哪一组偶尔掉下来可以先记下来、看到什么情况先别改动、先来问一句。
这样写的原因很简单:接手的人第一件事不是改东西,而是先确认东西现在是什么状态。先跑一遍文件,五组结果一出来,工具的现状就摆在眼前了。有一回我隔了一周回来,先跑了一遍文件才发现第三组分类偏了——上次改输出格式时动过分类规则。没有这一步,我会在偏了的状态上继续改,越改越偏。
写说明的时候,我给自己立了两条规矩。第一条是只写“先做什么、看到什么算对、看到什么先别动”,不写“这个工具能做什么”。功能列表看着全,对刚接手的人没用——他需要知道的是第一步迈哪只脚。第二条是说明里提到的每一处,都要能找到对应的东西:提到回归文件,就写清文件名和放在哪里;提到期望答案,就说在文件的每一段里。
文件和说明还要保持一致,这是最容易松掉的地方。回归文件换了一组输入,说明里还写着旧的五组,接手的人跑到一半就对不上号了。我的做法是:每次改文件,都顺手看一眼说明里提到文件的那几行,改了什么就改什么。改动小的时候,这一步只要半分钟;等到不一致攒多了再对,就要翻半天。
对我来说,这一步是前三篇的落点。固定输入模板让每次改动都有对照,回归清单让每次大改都有底线,存成文件让这份底线每次都能原样跑出来,写进说明让这份底线不只属于我一个人。下一步我会把每次跑文件的结果也记下来,每周看一次哪一组总掉下来、哪一组稳到可以换掉,让清单跟着实际用起来的情况慢慢变,而不是凭感觉换。
- 点赞
- 收藏
- 关注作者
评论(0)