如何撰写技术文档

先确定一个任务、一个读者和一个唯一信息源。然后用简明语言写出步骤，找一个没有写过这些内容的人来测试，再删掉任何不能帮助读者完成工作的内容。

写作前

好的技术文档，从第一句之前就开始了。先选一个任务。比如，写“连接新的支付网关”，不要写“记录这个应用”。这样，您就有了清晰的完成目标，页面也更有用。

接着，明确读者。开发者需要安装说明、命令和边界情况。支持人员需要症状、检查项和修复方法。项目负责人可能需要状态、依赖关系和交接说明。一页内容，可能只适合其中一种读者，或者三种都不适合。

然后收集唯一信息源。它可以是代码、工单、截图、设计说明、日志、运行手册，或者一本旧手册里仍然有价值的某一节。如果两个信息源说法不一致，先停下来，确认哪个为准，再开始写初稿。

开始写之前，先选好格式。安装指南、参考页面和故障排查页面，结构各不相同。对于一个升降桌控制器，安装指南可能解释配对和校准。参考页面可能列出按键名称和指示灯含义。故障排查页面可能说明卡住的升降或闪烁的错误灯。

如何撰写技术文档

• 先写结果。告诉读者，页面完成后他们能做什么。比如：“到最后，您会让测试环境应用连接到 Stripe。”
• 用一个简单流程：目的、您需要什么、步骤、结果、修复方法。这样读者就能一直往前走。
• 每一步只写一个动作。“打开管理控制台。选择计费。选择添加付款方式。” 这比一大段里塞五个动词更容易跟上。
• 按钮、字段、文件夹、命令、错误代码和文件名，都要用准确名称。如果屏幕上写的是添加付款方式，文档里就不要改成新卡。
• 术语要统一。如果第 1 步用的是 workspace，第 4 步就不要改成 project area。
• 把最可能的问题放在引发问题的那一步旁边。如果访问权限经常是问题，就在那里说明。比如：“如果按钮不见了，请确认您有 Billing Admin 权限。”
• 针对软件和代码，使用可直接复制的示例。先展示命令，再紧跟着展示预期结果。这样读者可以快速核对自己的屏幕。
• 写短段落。每段一个想法就够了。如果一段里想法太多，就拆成两段。
• 删掉任何不能帮助别人完成任务的内容。背景信息只有在能避免错误时才有用。
• 在结尾加上下一个步骤。比如，链接到测试页面、故障排查页面，或者接下来的设置部分。

一个简单的步骤模板

稳定的步骤格式，能让文档在任务变复杂时仍然易读。每一步都用这个结构：动作、结果、必要时的修复方法。这适用于软件设置、项目交接和基于命令的工作流程。

给开发者页面的例子：“运行 npm install。您应该会看到软件包列表更新。如果失败，请检查是否已安装 Node 20。” 这样读者就有了要做的事、要期待的结果，以及要检查的内容。

前： “然后处理依赖问题。” 后： “运行 npm install。如果看到权限错误，请以有写入权限的用户重新打开终端。” 第二种写法更难写，但使用起来更快。

对于桌面控制器页面，您可以这样写：“同时按住上键和下键三秒。显示屏应该闪烁一次。如果没有，请拔掉控制器再试一次。” 这样表达清楚、可测试，也很具体。

好的技术文档包含什么

一页有用的内容，通常会按这个顺序：标题、简短开头、前提条件、步骤、预期结果、修复方法、下一步。这个顺序之所以有效，是因为它按读者提问的顺序来回答。

标题要点明任务。开头要告诉读者，这页是给谁看的，以及覆盖什么内容。前提条件只列出会阻碍进度的内容，比如账户、线缆、版本或登录信息。

步骤要按真实顺序写，而不是按听起来聪明的顺序写。只有在真正需要的地方才放警告。为最常见的遗漏增加一个简短的修复部分。最后给出清晰的停止点，比如一次测试运行或一次交接。

对于支付网关设置页面，可以这样写：“将 Stripe 连接到测试环境应用。您需要管理员权限和测试密钥。按步骤粘贴密钥、保存设置，并运行一次测试扣款。如果测试失败，请检查密钥和账户权限。然后转到 webhook 设置页面。”

发布前先测试

不要因为草稿读起来顺，就相信它没问题。把它交给一个没有写过这些内容的人。请他们在没有帮助的情况下跟着做。观察他们在哪些地方停顿、猜测或回头。

如果他们停顿，页面可能缺少前提条件或一个小的设置步骤。把这一步加到他们第一次需要它的位置附近。

如果他们在猜，说明措辞不够清楚。把“输入正确的值”改成准确的字段名、标签或文件路径。

如果他们回头，说明顺序不对。把步骤提前，或者把页面拆开，这样读者就不用来回跳。

要修的是让人困惑的部分，不只是那一句话。有时候，真正的修复是新增前提条件、替换截图，或者另起第二页。

快速检查时，可以运行 tools manual check。如果您在实体说明上也需要同样的习惯，可以把结构和 this guide 对照一下。

通常哪里会出问题

最常见的问题，是背景信息太多，行动太少。读者在看到按钮名称之前，不需要先上历史课。

另一个常见问题，是把多个任务混在一页里。安装、故障排查和参考内容都会争抢空间。当读者需要切换思路时，就把它们拆开。

截图很容易过时。只把它们用于很少变化的界面。每当标签经常移动时，用简短标注或裁剪图片，别用整屏截图。

含糊的词也会带来麻烦。请删掉“simply”“easily”和“just”。它们并不能修复卡住的部署或缺失的权限。

当页面显得内容过多时，先删掉多余部分。保留能让读者得到可用结果的步骤。

需要多长时间

如果源文件整洁，任务也简单，一页简短的操作说明可能只要 30 到 60 分钟。

一份常见的软件安装指南，通常在您把起草、步骤检查和编辑都算进去后，需要 2 到 4 小时。

更大的项目页面，如果包含边界情况、截图和多轮审阅，可能会花去大半天。

慢的部分通常是证明步骤可行，而不是把它们打出来。如果流程很乱，您在操作时就一起写文档。这样能很快发现漏掉的点击、隐藏的假设和别扭的措辞。

什么时候视频版更有帮助

书面页面仍然最适合搜索、查阅和复制准确文字。若任务步骤很多、界面会变化，或者支持问题反复出现，视频会更有帮助。这在入门引导、安装和实际操作流程中很常见。

如果您已经有组装说明书或说明页面，可以在旁边放一个简短的视频版本。Manual to Video 会把现有说明书转成带动画、带字幕的组装说明视频，并使用您的品牌色和 logo。它也可以配合说明书、包装盒、产品页面或帮助文章上的 QR 使用。