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

这是对 31 位来自初创公司、大企业和开源项目的资深技术写作者的半结构化访谈。作者描述了五个审阅阶段:28 人描述了由工程师或其他领域专家做的技术审阅,它能挖出别处没有写下来的知识;13 人描述了「试玩测试」—— 由了解产品但没有参与写文档的人从头到尾照着文档操作,找出作者因为太熟而看不见的问题,主要用于教程;25 人认为大模型生成的审阅意见不可靠,部分原因是审阅所需的背景在不能分享给模型提供商的内部机密系统里。写作者说他们没有权力要求别人审阅,只能去争取。这是对自报做法的定性研究;作者之一任职于出售语言模型的公司。

一件工具在真实工作里被大规模使用,并且被测量到 —— 而做出「用它」这个决定的是使用者本人,不是雇主。它比「技术能力」多:干的是真活,不是演示;又比「实际部署」少:没有任何雇主把它投入生产、要求使用、或围绕它改过流程。权重定为 `cautious`:`automating` 的定义是「机器能做这件事**并且**有采用迹象」,而这就是一种采用迹象 —— 但使用可能只是试用,而且相当一部分测量来自有利害关系的一方,所以一条永远不够,两条独立的才够。还要注意是谁在计数。厂商遥测直接看得见这件事,而它同时在卖这件工具,所以这类记录要在适用范围里写明这层利害;而一个统计机构去问企业「员工有没有在任务里用 AI」,看见的是同一条通道、却没有任何利害 —— 在它存在的地方,它是更好的来源。

这是 FDA 给医疗器械企业的指南,注明为不具约束力的建议。它涵盖使用说明、用户手册、包装说明书和快速入门指南等标签内容,并说:人因验证测试可以评估使用说明是否充分,但只能在使用器械的情境中评估;对测试参与者最重要的考虑是他们能代表预期用户群体;如果测试发现关键任务上出现使用错误,仅称通过修改使用说明或其他标签降低了风险是不可接受的,除非提供额外的测试数据证明修改有效。它只适用于医疗器械,也没有说由谁来写说明。

失败、撤回、监管或成本正在抑制采用。可以下调评估,或扩大不确定区间。

在韩国法制处自家的国家法令信息中心上逐条读的法条,版本为 2026 年 7 月 21 日起施行。第三十四条第一款里有两项与这个职业有关,而它们做的是两件不同的事。第二项要求经营者建立并实施一套说明方案,在技术上可行的范围内,说明人工智能得出的最终结果、得出该结果所用的主要标准,以及开发与使用中所用训练数据的概要。第五项要求撰写并保管「能够确认安全性与可靠性措施内容」的文档。前者管的是一份参考文档必须覆盖什么,后者拿掉的是「可以不写」的自由裁量。第三十六条第一款第三项接着说的是维护而不是撰写:用户数或营业额达到总统令标准的境外经营者,须指定国内代理人,其代理事项包括为履行第三十四条第一款各项提供必要支持 —— 并明文包括对上述文档「最新性与准确性」的检查。两点限制。该法把细节交给总统令与长官告示,而第三十四条第二款写的是长官「可以建议」经营者遵守该告示 —— 所以「到底必须写到多细」并没有被这条记录定死。它只约束在韩国提供高影响人工智能的经营者;这里没有对任何技术写作者、任何一份文档、任何工时做计数。

监管、补贴或公共采购正在要求或出资推动采用 —— 与「限制或撤回」互为镜像。它说明采用正在被要求,不说明采用已经发生,所以单独一条永远不够,两条互不相干的才够。

具全国代表性,参照期 2025 年 11 月至 2026 年 1 月。这是同一份专项里的「员工任务」那一层,不是「公司采用」那一层:23% 的企业(按雇佣人数加权 41%)报告员工在与工作相关的任务里使用 AI;而在被报告的任务中,写作、文档分析与信息检索位居前列。它计的是「报告了某项任务的企业数」,不是「有多少写作是这样完成的」;它也不区分技术文档与其它写作 —— 没有人问过写的是什么。它在这里的价值恰恰在于它不是什么:与厂商遥测不同,这是一个统计机构在计同一条通道,而它对答案没有任何利害 —— 所以在它存在的地方,它是「使用者采用」更好的来源。

一件工具在真实工作里被大规模使用,并且被测量到 —— 而做出「用它」这个决定的是使用者本人,不是雇主。它比「技术能力」多:干的是真活,不是演示;又比「实际部署」少:没有任何雇主把它投入生产、要求使用、或围绕它改过流程。权重定为 `cautious`:`automating` 的定义是「机器能做这件事**并且**有采用迹象」,而这就是一种采用迹象 —— 但使用可能只是试用,而且相当一部分测量来自有利害关系的一方,所以一条永远不够,两条独立的才够。还要注意是谁在计数。厂商遥测直接看得见这件事,而它同时在卖这件工具,所以这类记录要在适用范围里写明这层利害;而一个统计机构去问企业「员工有没有在任务里用 AI」,看见的是同一条通道、却没有任何利害 —— 在它存在的地方,它是更好的来源。

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

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

调整职责

正式成为「第一个用户」

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

相邻转岗

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

在受监管的领域,文档是规则所要求的 —— 韩国的 AI 法要求高影响运营者编写并保存证明其安全措施的文件 —— 于是撑住它的是法律,不是预算。

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

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

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

有实质差别,而且它是本页最清楚的一个例子:一项被「成本以外的东西」撑住的任务。在医疗器械里,使用说明是按有代表性的用户用这台器械的实际表现来评判的,而且 FDA 的指南说,不拿出新的测试数据、只靠改写说明来修正一个使用问题是不可接受的 —— 也就是说这份活不能简单地生成了就发出去。那是政策保护而不是技术保护,耐久的时长恰好等于那条规则存在的时长;但它今天是真实的。