优秀文档的三个基本要素

我最初写这篇文章是为了回应@nonlinearnygma的帖子：

内容太长了，我觉得单独留这么长的评论有点不礼貌，所以决定单独发一篇文章。显然，我对文档有很多看法！这篇文章主要讨论优秀文档的要素，以及项目新手如何参与文档编写。

更新：写完这篇文章后，我发现@ojkelly也写了一篇非常类似的文章，描述了分层文档编写方法：

优秀文档的四个层次

欧文·凯利 ・ 2018年6月7日 ・ 阅读时长：5分钟

#文档 #文档 #营销 #写作

我非常喜欢他描述事物层层递进的方式，所以一定要去看看那篇文章。

但没人喜欢写文档……

如果你有这种感觉，你并不孤单。当你需要编写代码时，编写文档往往感觉不是首要任务。但好的文档能让代码更易于复用和理解，代码和其他程序员都会感谢你。在编写代码的同时也编写文档，可以让这项工作更轻松愉快。

编写文档对您有帮助

编写文档是深入思考技术细节的绝佳方式。它能帮助你重新审视问题，从而获得关于项目或改进方向的全新见解，这些见解可能是你之前没有想到的。它甚至可以在项目或新功能的规划阶段提供帮助。有些人甚至实践文档驱动开发！

编写文档有助于社区发展

文档是大多数程序员尝试或学习新项目，或者遇到问题或尝试解决已熟悉项目中的新问题时首先会查阅的地方。这意味着，对文档的贡献对项目社区的积极影响甚至可能超过对代码的贡献。

GitHub 2017 年开源调查发现，开源领域面临的最大问题是“文档不完整或令人困惑”。该调查得出的最重要结论是：

文档具有很高的价值，但经常被忽视，它是建立包容性和无障碍社区的一种手段。

项目维护者和用户都会非常感谢任何贡献（无论大小）。

愿景文档

以下是一些我尝试学习的、带有文档的项目：

• VueJS
• SQLite
• FreeBSD（尤其是与 Linux 相比）
• Bunjil（我没用过，但@ojkelly在他的帖子中分享的这个 GraphQL 服务器文档真的非常棒）
• Docker （由@presto412贡献）
• AWS （由@technologymop提供）

所有这些项目都包含我下面描述的组件。如果你有特别喜欢的、文档完善的项目，请在评论区告诉我。我一直在寻找更多文档方面的灵感！

我的理想文档

我认为理想的文档通常包含 3 个部分。

1. 项目缘由/目标：项目的背景和目标
2. API/参考文档：编程接口的详细技术文档
3. 如何操作/示例/指南：基于示例的指南，用于完成特定任务

为什么/目标

• 这个项目最初建造的动机是什么？
• 有哪些类似的项目？它们之间有什么不同？
• 这个项目适合哪些类型的项目？又有哪些情况下其他项目会更好？

通常情况下，这个问题最好由项目作者来回答。如果可能的话，最好能听听他们的观点，并将其添加到文档中（如果文档中还没有相关内容）。有时人们会忽略解释项目可能不适用的场景，但这对用户来说非常有用且值得赞赏。

API/参考

• 不同的高级组成部分是什么？它们是如何组合在一起的？
• 底层数据类型和函数有哪些？它们的作用是什么？

通常情况下，这部分内容已经存在。如果没有，入门可能会非常困难。如果您在学习如何使用项目的过程中遇到任何不清楚的地方，这里是一个很好的建议修改意见的地方。维护人员有时会对这部分文档格外重视，因为它被视为权威的信息来源，但这也可以成为您了解项目细节的好机会。

这类文档的格式通常与编程语言相关，因为大多数编程语言都内置了从源代码注释生成文档的系统。使用该编程语言的人通常也期望看到这种格式的文档。

方法/示例/指南

• 如何安装该项目并运行一些基本代码？
• 使用本项目构建一个简单的应用程序需要哪些步骤？
• 针对项目所涉及的常见问题，你们采取了哪些措施？

这通常是改进空间最大的领域，也是项目新手最容易上手的地方。

文档的这一部分会手把手地引导用户，清晰地一步步完成操作，最终使用户获得能够解决实际问题的有效代码（或者清楚地说明如何将其应用于实际问题）。

你可以通过搭建一个基于该项目的小模型来编写这类文档，并在每个步骤中仔细记录你的操作，这样其他人就可以通过复制粘贴轻松上手。你可以轻松地将其转化为一份指南，引导用户从零基础逐步取得小成就，最终获得顿悟。

大多数参与项目的人都是新手，所以从新手的角度为其他新手撰写文档非常有价值。项目经验丰富的人可能反而难以从新手的角度看待问题，因此他们通常非常感激这种贡献。我认为这类文档对于提高项目的易用性大有裨益。

我很想看看大家对优秀文档的看法，可以在这里或者@nonlinearnygma的帖子下留言。你对文档是又爱又恨吗？有没有特别喜欢的 #nicedocs 文档？