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