优秀文档的四个层次

当我开始发布一些开源项目时，我深入研究了如何为它们编写文档。这是我发现的最有用的方法。

良好的文档需要四层，每一层都建立在前一层的基础上。

编写这些文档的最佳方法是从底层（API）开始，逐步向上（入门）。顺便提一句，文档的读者通常会从顶层开始阅读，但偶尔也会找到底层。即便如此，从底层开始编写也有助于更好地理解顶层。

API

这是代码中唯一可以自动生成的部分。
文档是专门为人类编写的，这通常意味着
需要人工编写。
如果您已对源代码进行注释，则可以从源代码自动生成 API 文档。

这应该是如何使用项目 API 的综合文档，通常由源代码生成。

你应该记录你的代码，这样12个月后再回头看的时候就能理解。自私一点，善待未来的自己，让他们知道你做了什么以及为什么。你不会记得的。（这样做的附带好处是，其他人也能理解。）

这个项目的基本构建模块是什么？试着把项目分解成几个部分，并对每个部分进行详细的解释。

这里的目标是解释项目的构成要素。所有实施你项目的人都应该阅读本节。你需要详细而透彻地阐述。你不需要就每个要素都写一篇文章，几百字加上一张图表就足够了。

如果你需要为某个概念写一页长文，请善待读者，并尽量将其分成几部分以便于参考。虽然有些人会从头到尾阅读，但更有可能的是，读者会略读，只留下当时最相关的部分。你只需要一些标题和目录。

指南或教程是解释如何使用您的项目解决特定用例的理想方式。

编写时应考虑最终用途，并考虑用户的使用场景和知识水平。过度解释总比不解释好。有些内容对你来说可能简单明了，但对用户来说却闻所未闻。

想想你最初启动这个项目的原因，并列出你想要解决的用例。为每个用例写一个小的用户故事可能会有所帮助，例如：“作为项目维护者，我希望了解如何编写优秀的文档，以便我的项目能够吸引更多用户”。编写用户故事的典型格式是：“作为[角色]，我可以[实现]某个功能，从而[实现]某个原因”。

在最后一段中，我做了两件事。首先，我提到列出用户故事列表有助于确定要编写的指南，然后我给出了一个用户故事的示例以及编写它们的模板。你本来可以自己搜索来了解什么是用户故事，但我在这里直接解释它，不仅节省了你的时间，还消除了我们讨论内容的歧义。用户故事对你来说可能含义略有不同。

回到指南。你至少需要 3 到 5 个指南来解释如何使用你的项目。可以是如何在特定的操作系统上使用，也可以是如何与 3 个最流行的框架集成。

或者，如何整合并关注上一节中的特定概念。

发布项目时，您很可能会有 1-3 份指南。当出现问题和常见问题时，请将它们转化为指南。

这是您将要编写的最重要的部分，并且不包含单个“入门”页面。

如果你的项目是一个小型库，那么只用一个“入门”部分就足够了。通常情况下，你只需要一个主要概念，以及一组作为“指南”部分的示例。

首先，确定你的落地页是什么。你可能有一个网站，一个 GitHub 的 readme 文件。你也可能有一个关于 npm、godoc、pypi 或其他包管理器的页面。通常，除了网站之外，所有这些页面都会直接复制你的 readme 文件，所以让我们从这里开始。

首先，您需要清楚、简洁地回答以下问题：

这个项目叫什么？这个项目做什么？

然后，解释如何获取它。可能是通过包管理器下载，也可能是指向包含二进制文件的发布页面的链接。

现在，展示一个简单的用例。这里展示的是项目的公共接口。对于许多项目来说，最好的入门指南就是直接展示实现代码。不必展示所有内容，只要足够运行一次即可。

我们现在位于 readme 文件的页脚部分。最好能添加一些关于如何在这个项目上进行开发的信息，所以这里应该包含一些关于如何设置开发环境以及如何运行测试的示例。

强烈建议包含有关如何为项目做出贡献、在哪里提出问题、新功能和拉取请求的流程的信息。

如果您使用 SemVer，则应该包含有关 SemVer 的信息。（如果您尚未使用 SemVer，请考虑使用——您的用户会感谢您的）。

许多项目也喜欢在页脚区域承认其主要作者和贡献者。

最后，在最底部添加许可证。这通常是许可证类型的说明，并包含指向 LICENSE.md 文件的链接。您必须添加许可证，否则人们会对您的项目产生疑虑。

你不需要它们。虽然它们对你的用户有用。请自行判断，不要过度。它们可以提供一些社会认同。

如果您有网站（并非总是需要），您的“入门指南”包含首页和专门的入门页面。如果您想将两者放在同一个页面上，只需确保有一个链接，让读者可以直接跳转到“入门指南”部分即可。

首页通常包含与自述文件相同的信息，并且通常采用美观的设计。不要在这里过度设计，你的重点是可读性。有时，精美的图形或动画可以提升项目的传播度——但不要为了追求这一点而牺牲实际用户的体验。

文档是项目最好的营销工具，也是项目可信度和成熟度的最佳指标。完善项目文档需要付出努力，但如果你想吸引用户，这一切都是值得的。

作为这种文档方法的一个例子，您可以查看我最近发布的Bunjil项目。