夜雨聆风写作篇：写给用户，不是写给产品
你有没有读过这种文档
打开一篇帮助文档，满眼都是"底层逻辑""技术架构""数据流转"，看了三遍还是不知道自己该怎么操作？大概率不是你理解能力的问题——是那篇文档写给了产品经理看，不是写给用户看的。
太多技术文档其实是产品文档的"翻译版"：把 PRD 里的逻辑梳理一遍，换个措辞，就当作帮助文档发布了。但 PRD 的读者是研发和测试，帮助文档的读者是正在遇到问题的用户——两群完全不同的人，带着完全不同的目的来读同一份内容。
从"写给产品"到"写给用户"的四条原则
原则一："不能说自己坏话"
迭代文档和新建文档最大的不同在于——迭代文档对应的功能已经存在，只是研发对它进行了优化或修改。产品文档（PRD）会详细描述修改原因，比如"因存在泄露个人隐私的风险，需加强数据加密"。这段描述在 PRD 里完全合理，因为受众是研发团队。但同样的信息搬到帮助文档里，就完全变了味：
第一句让用户恐慌——"我的数据是不是已经被泄露了？"第二句让用户安心——"产品在保护我的隐私。"措辞的差异不是字面功夫，而是你站在哪一边的问题。用户文档的职责是描述"现在"，不是暴露"过去"。
注意一个关键细节："不能说自己坏话"不等于"隐瞒问题"。如果某个优化确实改变了用户需要知道的行为（比如操作路径变了、某个配置项移除了），你当然要如实告知。转变的是措辞的焦点——从"我们修了一个问题"变成"你获得了一个更好的体验"。
原则二：通俗易懂——用户要的是操作，不是原理
产品文档里对埋点、数据流、调用链路、状态机都会做详细描述，因为研发团队需要这些信息来实现功能。但用户只需要三件事：
帮助文档不是 API 文档。帮助文档服务于"使用产品"的场景，API 文档服务于"开发集成"的场景。就算用户是程序员，他来查帮助文档的那一刻，角色也是"使用者"而不是"开发者"。
先说"能干嘛"，再说"怎么干"
通俗易懂不只是"少写技术细节"，还关乎信息呈现顺序。你一定见过那种上来就写操作步骤、但完全不告诉你这个功能能用来干嘛的文档。用户跟着步骤点了一遍，操作完了，却依然不知道自己为什么要做这件事——就像给你一把钥匙，但不告诉你开哪扇门。
先告诉用户"你找对地方了"，再告诉他"怎么做"。这个顺序不能反——反了，用户就是被你领进一个房间，却发现房间里的东西跟自己毫无关系。
原则三：配图配图配图
配图可能是技术文档里投入产出比最高的一件事。人的大脑处理图像的速度是处理文字的 6 万倍。"点击右上角齿轮图标旁边的下拉箭头，选择'系统设置'"——你试试找这个按钮，对比直接在截图上画个红圈，体验差距是指数级的。
找不到配图？问测试。不要怕打扰别人——用户看到一篇没有图的文档，比你去问同事要一张截图，要烦得多。而且用户一旦烦了，他不是来"打扰"你，而是直接关掉文档去骚扰技术支持了。
原则四：写作风格规范
技术文档不是文学作品，但它也不是草稿。读者要在最短时间内获取准确信息，每一个多余的词、每一个含糊的句子，都是障碍。核心维度有三条：
① 用规范中文，别中英混排
有些术语确实没有好的中文翻译（比如 API、SDK），或者中文翻译反而不常见，这种情况保留英文是合理的。判断标准：哪种表达对目标读者来说更自然，就用哪种。
② 用主动语态，别绕弯子
被动语态多了一个"被"字，读者需要多绕一步才能理解谁在执行动作。在操作步骤里，这个问题尤其严重——"按钮被点击"vs"点击按钮"，信息量一样，认知负荷完全不同。
③ 操作步骤用祈使句
陈述句把主语"用户"放在前面，还加了"需要""找到""并"这些连接词。祈使句直接砍掉主语，动词开头，一步一指令，用户扫一眼就知道该做什么。
严谨与引导的平衡
两种极端的后果都很严重。怎么平衡？分层呈现：
举个例子：一个"导出数据"的功能，主干步骤只写"点击导出 → 选择格式 → 下载"，三步搞定。参数说明放在后面，列清楚每种格式的区别、文件大小限制、编码选项。高级用法再单独写定时导出、API 调用批量导出。80% 的用户看完主干步骤就能完成任务，20% 的进阶用户也能找到自己需要的深度信息。
最后一条"元原则"
前面四条原则讲了"不能说什么""该怎么说""要配图""用什么风格"，但所有这些原则都有一个共同的前提——你必须自己实际操作一遍。
这不是可选项。如果你没有亲自操作过那个功能，你写出来的文档一定会有盲区——某个按钮在不同系统下的位置不同、某个步骤在特定条件下会报错、某个配置项改了之后需要重启才能生效……这些细节，PRD 里不会写，研发也未必告诉你，只有自己点一遍才能发现。
立刻可以做的事
