writing-user-docs

面向用户的文档

面向工具的使用者写作，而不是面向构建工具的人。

“用户”指使用某样东西的人。对于应用来说，用户是最终用户；对于库来说，用户是安装它的开发者。无论哪种情况，他们都不是在实现它，文档也应体现这一点。

语气

使用日常英语，就像向坐在你旁边的同事解释一样。正式并不会增加权威感，只会拉开距离、增加字数。

• 使用第二人称、主动语态和现在时。 写“你点击 Save”，不要写“应点击 Save 按钮”或“用户随后就能保存”。
• 删掉“just”“simply”“easy”“obviously”。 一切正常时，这些词毫无用处；出了问题时，它们读起来像是在嘲讽用户。
• 不要使用营销形容词。 “强大”“无缝”“稳健”“直观”——这些只是作者在赞美产品。读者正在处理任务，并不在意这些。
• 每个概念只用一个术语，并与 UI 完全一致。 如果按钮写着 Workspace，文档就不要称它为“项目”或“团队空间”。变换用词是好文章的写法，却是糟糕文档的写法——每个同义词看起来都像一个新概念。

范围：写什么

只写读者使用工具所需的信息。默认做法是删掉其他内容。

不要写实现细节。 不写数据库、队列、框架、算法名称、内部服务，也不写为交付产品而进行的重构。判断标准不是“这是否具有技术性”，而是**“如果不写，读者会感到意外或做出错误决定吗？”**

可观察到的行为符合这个标准，即使听起来很技术性，也应写入文档：速率限制、离线行为、同步内容及同步时间、文件存储位置、冲突时的处理方式、重新安装后保留的内容。产生这些行为的机制则不应写入文档。

简洁意味着没有赘述，而不是篇幅短。 每句话都要有存在的理由。详尽的故障排除部分，只要没有一句是在凑字数，就仍然简洁；而只有两行的页面，如果其中一行是欢迎语，也显得臃肿。删掉铺垫、重复标题的内容，以及“本文将介绍”。

结构

• 按用户目标组织内容，而不是按功能或屏幕组织。 标题应写人们想做的事，例如“与团队外的人分享报告”，而不是“分享模块”这样的名词。
• 先说明结果，再列出步骤。 在开始第 1 步之前，读者需要知道自己是否找对了页面。
• 把前提条件和限制放在开头。 所需套餐、权限、平台、文件大小上限等。到了第 6 步才发现无法继续，是最糟糕的情况。
• 一个页面回答一个问题，并且独立完整。 大多数读者通过搜索或深层链接进入页面，而不是从第 1 页开始。假设没人读过前一页；用链接代替假设。
• 只选一种操作路径。 如果有三种方法，只记录推荐的方法。其他方法可在末尾简短说明，也可以不写。

说明出错时的处理方式

这是最容易被跳过的部分，也是人们实际最常搜索的内容。

• 记录失败情况：错误提示是什么、由什么原因导致、接下来该怎么做。
• 对于用户容易想当然认为功能支持的情况，明确说明功能不支持什么。 这比处理支持工单更省事。
• 在破坏性操作之前发出警告，绝不要事后才警告。 警告应放在它所适用的步骤之前。

防止内容过时

• 使用真实、看起来可信的数据举例。 不要用 foo、test123 或 lorem ipsum。示例应可直接复制粘贴，并能生成所展示的结果。
• 不要使用相对时间表述。 “新”“最近”“目前”“即将推出”——这些说法都会悄然过时。路线图承诺也一样。
• 逐字逐句地检查每个操作流程。 如果有人逐字照做却无法完成，说明文档有问题，不是读者的问题。

发布前

通读草稿，只检查以下几点：

1. 读者完成任务不需要的信息 → 删除。
2. 内部工作原理相关内容 → 删除，除非用户可观察到的行为取决于它。
3. 任何你不会大声说出来的句子 → 改写。
4. 出问题时会发生什么 → 是否已说明？