技术文档工程师 / 技术写作 · 任务逐条

起草参考文档

这是本站暴露度最高的一项写作任务 —— 因为事实来源是机器可读的,而输出格式是固定的。从函数签名生成参数表,在模型出现很久以前就已经被文档生成器部分自动化了;模型加上的是「读起来像人写的」散文,而那拿掉了「让人来写」的最后一个理由。

被生成的参考文档,是一份发布前没人读过的参考文档;而它的失效方式不是「错」,是「看起来对」—— 它描述的是代码声明了什么,不是代码做了什么。这个缝隙只有真的去用它的人才会发现,而那正是下面那项任务 —— 所以把这一项自动化,抬高的是那一项的价值,不是拿掉这份工作。

真的去用你要写的那个东西

这项任务的输入不存在于任何代码库里:它是「在某个具体位置被卡住」的那份体验。一个在这套代码上训练过的模型,继承的正是工程师的知识 —— 而这份知识恰恰必须缺席,这个测试才成立。这里的价值来自「不知道」。

这项任务是这个职业最强的论据,也是在预算会上最弱的一个 —— 因为它的产出是一种缺席:那些没有发生的支持工单。在文档团队被裁的地方,最先走的就是这一项,而这件事完全不需要技术来促成。

决定什么不写

生成变便宜让这一项从最不值钱变成最值钱的一项,因为瓶颈挪了:当「把所有东西都写出来」变得可能时,「选」就成了这份工作的全部。决定省略什么,取决于知道有哪些用户、他们想做成什么 —— 而那不在代码里。

更值钱不等于被认可:文档通常按覆盖率考核,而覆盖率恰恰是「生成变便宜」让它失去意义的那个指标。一个按「发布了多少页」被考核的团队,会在这项任务刚变成最要紧的那一刻,因为放弃它而被奖励。

把答案从工程师嘴里挖出来

需要的信息按定义就是没有文档的 —— 如果它被写下来了,这项任务就不存在。把它挖出来是一个社会行为,对抗的是别人的日程表;而这里的本事是知道「问哪一个问题会得到真实的答案、而不是官方的答案」。

正是这项任务让这份工作很难远程、兼职或由外包来做 —— 而那恰恰是成本压力推着它去的方向。这里的威胁不是自动化,是这份工作被重组成一种「容不下这项任务」的形态;在那之后文档会变差,而没有人会把原因归对。