技术文档不是代码编译完成后才去做的琐事。它处于每个软件项目的核心位置，决定了新开发者能否在入职第一天就修复 Bug，或者用户是否会在五分钟的困惑后放弃你的产品。优秀的文档能帮助用户完成实际任务。它们能帮助未来的维护者理解某个模块存在的意义，以及如何在不破坏整体功能的情况下对其进行修改。然而，太多团队将文档视为事后才考虑的事情，要么是匆忙拼凑的 README，要么是任其荒废的 Wiki 页面。编写真正有用的文档是一项可以通过刻意练习来提升的技能。
动笔之前，先了解你的读者
在敲下第一个标题之前，先确定谁在阅读。寻找连接池设置的数据库管理员，与寻找 React 组件属性的前端开发者完全不是一类人。终端用户需要的是带编号的步骤和截图，而不是架构图。他们想知道如何导出 PDF，而不是渲染流水线是如何工作的。集成你库的开发者需要准确的函数签名、错误代码和可直接复制的代码片段。系统管理员需要安装前提条件、环境变量，以及从最常见的故障模式开始的排障流程。
如果你试图用一大段文字同时服务这三类群体，结果将是全军覆没。创建不同的路径。即便是单个页面，也可以通过“面向运维人员”和“面向客户端开发者”这样清晰的标题进行有效划分。目标是消除读者在阅读时产生“这段话是写给我看的吗？”这种心理摩擦。
删繁就简
清晰胜过巧妙。使用短句。使用主动语态。“初始化数据库”比“数据库应由用户进行初始化”更清晰。当必须使用“幂等性 (idempotency)”或“序列化 (serialization)”等技术术语时，请在文中直接定义或链接到术语表。不要假设读者具备预备知识。
一个实用的测试方法：试着大声朗读你的段落。如果你读到断气，说明句子太长了。另一个测试方法：用简单的动词替换华丽的动词。如果像 “utilize the API” 这样的短语可以改为 “use the API” 且不丢失原意，那就改掉它。平实的语言并不意味着浅显易懂的“白话文”。它意味着剥离了企业套话的精准语言。
真正有帮助的结构
杂乱无章的手册比没有手册更浪费时间。将你的文档想象成一个漏斗。在顶部，放置一个简短的概述，解释项目的功能以及谁应该关注它。接着是安装说明，不要对读者的本地环境做任何假设。然后添加教程，带读者从头到尾走完一个完整的、真实的场景。接下来是 API 参考。这些内容应当详尽且易于扫读，按资源或功能进行分组，而不是按字母顺序堆砌。最后，放置针对特定症状的排障指南。收到 “Connection refused” 的用户需要的答案，与看到 “Permission denied” 的用户是不同的。按错误信息或上下文对错误进行分组，而不是按抽象的类别。
列表和代码块可以打破密集文本的沉闷感，让读者快速扫视并找到所需的精确命令。一个位置恰当的列表可以将一段令人困惑的文字转化为一系列清晰的操作步骤。
演示，而非空谈
抽象的解释会让用户感到沮丧。如果你描述如何配置工具，请展示确切的文件内容。提供用于安装、初始化和常见配置的代码片段。将示例输入和预期输出并排展示。如果你的 API 返回 JSON，就展示 JSON。如果 CLI 工具产生表格输出，就展示表格。永远不要认为对工作流的描述等同于实际演示。
最重要的是，在发布之前，在干净的环境中测试每一个示例。将你自己的代码片段复制到全新的容器或虚拟机中。如果因为它因为你忘记提及某个依赖项而失败，那么你已经为自己避免了后续排山倒海般的反馈问题。在技术写作中，具体的示例能提供最高的投资回报率，因为它们能将不确定性转化为行动。
保持文档的生命力
文档的腐化速度比代码更快。方法签名变了，默认端口改了，依赖项被替换了，突然间，你的说明就走到了死胡同