技术写作的艺术：如何写出让人读完的技术文档

为什么大多数技术文档很糟糕？

技术文档通常由工程师编写，而工程师往往犯同一个错误：以知识的诅咒写作——假设读者已经具备自己拥有的背景知识，跳过对初学者至关重要的解释。

文档的四种类型

Divio 文档系统将文档分为四类，每类服务不同的目的：

• 教程（Tutorial）：手把手带新用户完成第一个任务
• 操作指南（How-to Guide）：解决特定问题的步骤
• 解释（Explanation）：深入理解背后的概念和设计决策
• 参考（Reference）：完整的 API 和配置说明

写作原则

优秀技术文档的三个核心原则：从用户目标出发（而非功能列表）、用示例说话（代码胜于文字）、保持简洁（删除所有不必要的词）。

工具推荐

Docusaurus、GitBook、Notion 适合不同规模的文档需求。对于开源项目，推荐 Docusaurus；对于内部知识库，Notion 的协作功能更有优势。