技术文档工程师 / 技术写作

API 参考、参数表、发布说明、变更日志条目 —— 内容由代码决定的那类文档。

在一台干净的机器上照着自己写的步骤走一遍,找出那个「对工程师显而易见、对其他所有人不可能」的步骤。

在整个功能面上挑出该被好好写的那两成,并且拒掉其余的。

弄清楚五个人里哪一个知道它为什么这样,并从他那里要到十五分钟去问明白。

过去招你进来的那项任务 —— 产出参考文档 —— 是本站暴露度最高的一项写作任务。现在稀缺的是那项没有人直接招聘的:做那个「不知道的人」,照着步骤走,并找出那个不可能的步骤。要让这件事在你的工作方式里被看见,因为它是「起草变便宜」之后唯一还站得住的论据。

你的团队会按覆盖率被考核,而覆盖率刚刚变成免费的 —— 于是指标会非常好看,同时文档以一种「从看板上看不出来」的方式变差。值得摆到管理者面前的数字是「排名前十的文档页面上的支持工单数」,因为那是文档真的变好时唯一会动的那个测量。

调整职责

正式成为「第一个用户」

模型唯一拿不到的文档输入,就是「被卡住」的那份体验;而一个发布很快的团队,需要有一个人,他的工作就是在客户之前故意被卡住。

相邻转岗

转到「文档本身是合规交付物」的那一侧

在受监管的领域,文档有被规定的形式,并且有一个具名的人为它背书 —— 于是撑住它的是法律,不是预算。

起草参考文档是本站暴露度最高的一项写作任务,因为事实来源是机器可读的、输出格式是固定的 —— 而且在模型出现很久以前,文档生成器就已经拿走了其中一部分。不会动的是那个测试:在一台干净的机器上照着自己写的步骤走,找出那个「对不是工程师的所有人都不可能」的步骤。一个在这套代码上训练过的模型,继承的恰恰是「必须缺席这个测试才成立」的那份知识。

不给日期。信号是你的团队被什么考核。如果是「发布了多少页」或覆盖率,那这个指标刚刚变成免费的 —— 它会非常好看,同时文档在变差,而人数决定就是照着那块看板做的。盯住有没有人在跟踪「排名前列页面上的支持工单」,因为那是文档真的变好时唯一会动的测量;而它存不存在,会告诉你下一次预算会怎么走。

在生成变便宜的那一刻,它就不再是了 —— 而这是这个职业里后果最大的一个变化。覆盖率现在测量的是「存在多少文字」,不是「有没有人能靠它做成什么」;于是一个按覆盖率考核的团队,会因为放弃那项刚刚变成最要紧的任务(决定什么不写)而被奖励。如果你的团队还在报覆盖率,把这件事提出来,比再写一页更有价值。

有实质差别,而且它是本页最清楚的一个例子:一项被「成本以外的东西」撑住的任务。在医疗器械、航空与药品申报里,文档本身是合规交付物:形式是被规定的,而且有一个具名的人为它背书 —— 也就是说这份活不能简单地生成了就发出去。那是政策保护而不是技术保护,耐久的时长恰好等于那条规则存在的时长;但它今天是真实的。