写作原则
- 保持简洁。 人们阅读文档是为达成目标。尽快切入要点。
- 清晰优先于巧妙。 表达要简单直接，避免术语或复杂句式。
- 使用主动语态。 与其说“应创建一个配置文件”，不如说“创建一个配置文件。”
- 便于浏览。 用标题帮助读者定位，拆分长段落，使用项目符号和列表以便快速扫读。
- 使用第二人称写作。 直接指向读者更便于他们按步骤操作，也让文档更具亲和力。
常见写作错误
- 拼写和语法错误。 即便只有少量拼写和语法错误，也会削弱文档的可信度，并降低可读性。
- 术语不一致。 在一段中将某个概念称为 “API key”，下一段又叫它 “API token”，会让用户难以理解和跟上内容。
- 过于以产品为中心的术语。 你的用户并不具备对你产品的完整上下文。应使用用户更熟悉的语言。
- 口语化表达。 尤其在本地化场景下，口语化表达会降低内容的清晰度。