被动语态：谁在操作？系统还是我？
"配置文件需要被修改"——我读了三遍，还是不确定是我改还是系统改一句话让我读了三遍
我读过一篇部署文档，里面有句话：
我读了三遍，不确定是我改还是系统自动改。如果是系统自动改，我不需要做什么；如果是我改，我需要知道改哪个文件、改哪个字段。
被动语态在技术文档里最大的危害：操作主体不明确，读者不知道这个动作是谁做的。被动语态在文档中的三个危害
谁修改？用户还是系统？如果是用户操作，应该写"修改配置文件"；如果是系统行为，应该写"系统自动修改配置文件"。是我点了导出触发的？还是系统自动导出？如果是我触发的，写"数据将导出到本地目录"，省掉"被"字，意思更清晰；如果是系统自动的，写"系统将数据导出到本地目录"。这是操作步骤还是注意事项？如果是步骤，写成"设置环境变量"，以动词开头，明确这是一个用户需要执行的动作。改写前后对比
操作步骤里用主动语态（用户做的事），描述性内容里被动语态可以接受（"该接口已被废弃"、"数据已加密"）。「文档写作的坑」全系列回顾
第1篇 知识诅咒：你觉得"这还用说？"，读者觉得"这说的是啥？"第2篇 冗余的温柔刀：删掉20%，意思一点没变第3篇 前提条件藏在步骤里，是最坑的惊喜第4篇 一篇文档塞三个任务，谁都找不到自己要的第5篇 截图：维护的噩梦，还是沟通的利器第6篇 代码示例跑不通，比没有示例还糟第7篇 被动语态：谁在操作？系统还是我？ ← 你在这里七个坑讲下来，有一条贯穿始终：
写文档的时候，永远站在读者那边。
你觉得"显然"的，读者不一定觉得；你觉得"应该知道"的，读者不一定知道；你觉得"没问题"的，读者可能已经放弃了。
每一条坑，本质上都是写作者和读者之间的信息差。填平这个差，就是好文档。
夜雨聆风
