README是你的门面，如何写出一份出色的自述文档？

神译局是36氪旗下编译团队，关注科技、商业、职场、生活等领域，重点介绍国外的新技术、新观点、新风向。

编者按：自述文件是项目的首页，是你留给用户和贡献者第一印象的地方。第一印象不好，就没有后面的一切。所以写好自述文件太重要了。但怎么才能写好自述文件呢？请看经验之谈。文章来自编译。

一个系统或者产品要想吸引人，关键是什么？这一切都要从最重要的自述文件开始。自述文件是项目的首页——它通常是你给用户和贡献者留下的第一印象。有效的自述文件需要告诉受众项目是做什么的、应该如何使用以及可以提供什么帮助。

我们对此进行了优化，方法是将对最广泛受众最有用的信息放在前面，然后逐步深入到技术细节，每当需要更多细节时，我们会提供其他来源的链接，以避免大段文字，并在任何有可能的地方使用视觉效果。在本文中，我们将更详细地讨论这三个原则如何可以帮助你的项目做出一份出色的自述文件。

好的自述文件应遵循的原则

GitHub 上不乏可供贡献的项目，这意味着潜在贡献者很容易忽视那些还不是很受欢迎的项目，即便那些是很棒的项目。对于许多项目维护者来说，这种情况实在是有些苦涩，因为他们希望自己的项目能成功，因为项目本身质量很高。

为了确保你的项目不会被埋没，在不需要潜在贡献者付出大量努力的情况下，尽快传达项目的价值至关重要。最好的办法是提供一份清晰简洁的自述文件，这份文档不仅应该包含有所有的重要信息，而且还要看起来不错，且易于阅读。在本文中，我们推荐了实现这一目标的一些关键原则，并解释了我们是如何应用的。

你在看东西的时候，会从顶部开始，因此从最有用的信息开始你的自述文件，然后逐渐深入到技术细节。这可以防止读者在掌握了足够的上下文来理解项目的内部运作之前感到不知所措。

认识到不该放哪些内容进去也很重要。自述文件要言简意赅，并在需要深入了解细节的时候提供相关正式文档的链接，这样的效果最好。另一种做法是到处都是大段文字，这可能会让读者感到非常反感。

我们把自述文件看作是用户理解项目所需一切信息的中枢。它应该提供项目的总体概述，并向用户展示去哪里可以找到更多详细信息，包括它的工作原理、最新安装选项的链接，以及最后为贡献者提供的详细信息链接。

我们还认为，尽可能展示而不是光说是有好处的。我们建议用图标、图像以及 GIF 来让文档维系视觉上的吸引力，并提供可视化的路标 - 帮助读者快速导航到对他们来说重要的细节上。

如果说一图胜千言的话，那么一幅好的 GIF 就抵得上百万字。我们发现，如果项目的某个功能特别容易使用但很难用语言描述时，使用 GIF 是个好主意。我们的项目的一个例子是展示在 Appsmith 上快速开发美观、实用的应用是多么的容易，尽管幕后隐藏了大量用户看不见的复杂性。

GIF 和其他的视觉效果永远无法取代文档提供具体细节的工作，但在展示项目的用户界面时，它们绝对可以额外提供让读者“哇”起来的因素。它们可以让读者轻松快速地获取有关项目的大量信息，这是提高采用率并最终为项目做出贡献的关键。

自述文件解构

接下来我们就详细看看 Appsmith 地自述文件，好好研究一下每一节的设置，去弄清楚为什么我们要这样做，以及这份文档是如何运用上述原则，从而尽可能轻松地为读者提供他们需要的信息地。

标题

Appsmith 的自述文件以logo为开头，logo可以帮助用户直观地识别项目。为你的项目投资一个好的logo是非常值得的——就算你的项目不是以营利为目的，品牌认知度也至关重要。要让你的项目看起来专业且令人难忘，这一点非常重要，这样别人才能轻松找到你，并且不会被一个更好品牌的fork（分叉）取代掉。

接下来，我们用简短的两句话概述来介绍 Appsmith。概述只关注 Appsmith 是做什么的以及给谁用的，而没有讲它的工作原理；我们发现，工作原理部分太长会导致读者很快失去兴趣。至此，在深入讲解技术细节之前，读者应该能够在比较高的层面去决定项目是否与他们的需求或兴趣相关。

接下来，我们会提供一些自动统计的数据，让读者了解社区正在发生的事情。来自 Discord 社区的在线用户数量、commit的统计数据以及 Docker 的pull数据可以让用户了解有多少人对 Appsmith 感兴趣。看到社区很活跃，可以同时鼓励用户和贡献者加入该项目。

我们的自述文件标题的最后一个要素是 Appsmith 云端版的注册页面、我们的 YouTube 频道以及模板的链接。这些是新来者最常见的“后续步骤”，因此我们把它放在高度可见的位置。

第一部分中总共用了三个示例来说明项目的活动（Discord 用户、commit活动、Docker pulls），用了三个行动号召（入门、YouTube、模板）。乍看之下似乎内容很多，但每一个行动号召都带着不同的目的去呼吁用户行动，而且其他读者也不会因为它们的存在而受到负面影响。

我们相信，对于对本项目感兴趣的用户来说，学习如何使用这个项目是最重要的信息。不过，不同的用户喜欢用不同的方式去学习：有些喜欢看文字，有些喜欢看视频，有些喜欢参考示例模板。这就是为什么我们在自述文件添加了那么多不同的选项的原因，为的是向用户展示如何启动和运行 Appsmith。

根据所提供的信息，他们可以决定是不是已经找到了满足自身要求的项目，并找到了需要采取的下一步措施。通过运用好看的视觉效果和链接，我们将大量信息打包到一个非常小的空间内，不会导致读者感到不知所措。

Appsmith 的工作机制（针对最终用户）

接下来，我们将从较高层面介绍软件的工作原理。我们以标题的信息为基础，但提供了更多的详细信息，以便用户可以建立对软件的心智模式，从而理解其最基本的概念。不过现阶段我们还没有透露更深入的细节，这些可以稍后再详细阐述。

现在读者已经了解了上下文，接着我们用 GIF 动图来展示 Appsmith 的实际操作，去进一步扩展上面那张基本的流程图。在这里，我们想要传达的信息是，用 Appsmith 开发应用就像前面介绍的那四个简单步骤一样简单。我们还不想教给用户平台的内部运作方式是什么样的——那是以后的事了。但是，如果用户这个时候对更多详细信息感兴趣，他们可以点击我们网站包含的文档链接。

功能（针对最终用户）

直到现在，我们才讲到很多自述文件一开头就介绍的信息：详细的功能列表。到现在，如果读者一路读下来，他们已经了解了这个项目的意图了。或者，如果读者正在略读本自述文件（这种情况更为常见），那么很明显，该部分是针对更熟悉本项目，切正在寻找更多详细信息的用户的。

不管是哪一种情况，这一节都是我们向读者介绍更多细节的部分。在这一部分，文字的重要性将高于插图，因为我们在解释 UI builder、预置小部件、原生数据库集成等概念时要增加信息密度。

在自述文件的末尾，我们开始讨论真正的技术细节。为了保持自述文件的可浏览性，我们尽一切努力避免大段文字：用户应该能够在结构化、引人注目的格式引导下快速导航到主要章节。

为了帮助实现这一点，每个功能都加粗显示，并配上直观的图标，详细信息介绍最多也只有一个段落。我们还尽量在任何有意义的地方植入代码片段（比方说，在解释我们对 JavaScript 的支持时）。我们还提供了其他有用资源的链接，尤其是介绍加密货币等复杂主题的章节。

如何设置（针对最终用户）

到达此部分的用户要么已阅读过之前的内容并对项目感兴趣，要么已到了要寻找安装说明并直接单击标题相应的行动号召的地步。

我们的安装说明简洁且可操作，显示了我们的部署选项并链接到相关文档。我们还有许多其他的部署选项，但我们可以限制此处显示的选项，因为我们相信只向用户推荐最好的，并维持自述文件的可浏览性。

这种做法强调了项目的易于设置，并且拥有强大的社区支持。当然，我们仍然遵循以前的所有原则：我们很少依赖文本，尽可能用链接的方式介绍更多细节，并确保把易于观看的直观视觉效果放进去。

贡献者章节

这里是我们展示社区的地方，也是我们最喜欢的一节！在这一节里，我们会解释我们的价值观，以及我们如何确保维护好一个人们愿意加入的社区。然后，从如何做出贡献到如何设置开发环境，我们会解释对贡献者有好处的更多技术信息。

当你要围绕着项目建立社区时，行为准则对于塑造社区内部的沟通交流是有好处的。我们用行为准则来预先解释清楚我们打算建立的是什么类型的社区，哪些行为是不可接受的，以及如何执行这些行为准则哦。本节可帮助读者了解自己是否认同这里的价值观，以及他们是否应该相信这些价值观将会得到维护。

假设他们在阅读完行为准则后希望成为社区的一员，接下来的两个组件将向他们展示如何加入社区。贡献指南帮助新贡献者了解如何自己产生影响，而安装设置文档则展示了做出贡献是多么的容易。这两者的目的都是为了减少开始的阻力，让潜在的贡献者可以立即加入。

还有一个新增功能对我们来说非常有用，那就是 GitHub 中的“good First issues”章节。我们认为，让贡献者做出贡献的过程变得尽可能简单非常重要。为此，我们把 GitHub 上面那些未被解决的问题都标记为“Good First Issue”，这种做法也是 GitHub 过去几年所鼓励的，已经形成一种趋势。这有助于新的贡献者在不需要了解项目的深层、复杂的架构的情况下，尽早取得成果，改进项目。

所有这些组件对贡献者章节都发挥着不可或缺的作用。每一部分的文档本身都很简短，切中要点，以便我们在不需要大量文本的情况下传达出想要表达的讯息：我们正在建立的社区类型是什么，以及如何成为社区的一员。

然后，我们会以突出展示顶级贡献者来结束这份自述文件。我们希望向所有致力于让本项目变得更加出色的开发者展示，并鼓励其他人的加入。

自述文件中经常被忽视的部分——许可

补充说明一下，我们用项目许可的链接结束本自述文件。许可应该是存放在github仓库的独立文件，并以链接方式放在自述文件的底部。

很多人对许可这个东西都不不以为然，认为这个东西是无聊的法律组件，但你选择什么样的许可方式往往会对你的开源项目产生巨大影响。你的许可可能会影响你能吸引到什么样的用户和贡献者，并且在某些情况下还会影响到你创建的项目在数年后所衍生出来的项目的类型。

因此，预先对许可予以特别关注十分重要，要确保为你的项目选择短期和长期的最佳许可方式。关于如何为你的项目选择合适的许可有很多指南，其中就有包括来自 GitHub 的指南，因此这里不会过多介绍相关细节。

其他一些同样出色的自述文件

我们这样写自述文件当然不是唯一或最好的方式。每个项目都有不同的目标和期望。为了提供更多示例，我们还想在这里介绍我们喜欢的出自不同类型项目的自述文件。

一个写得很棒的包管理器自述文件

npm 是最流行的 JavaScript 包管理器。鉴于这是一个包管理器，所以很难通过视觉效果来解释这个项目。这个项目在自述文件本身的简单性方面做得很好，表述非常切题，也会链接到更复杂更详细的信息。

一个很棒的框架自述文件

Laravel（一个流行的 PHP 框架）的自述文件我们也非常喜欢。你可以看到，他们也关注到我们在自己的自述文件重点关注的许多原则，包括在需要更多详细信息时提供链接，以及避免出现大段文字。

Laravel 自述文件提供了大量文档链接，但更重要的是，它提供了社区学习资源的链接。其中包括介绍如何快速启动和运行的 Laravel Bootcamp ，以及综合视频教程库 Laracasts。开发者认为，这些资源是 Laravel 最受赞赏的地方之一，因此尽早（也就是在自述文件里）向潜在用户传达这一点非常重要。

有个地方我们的自述文件没有提供，那就是列出如何赞助本项目，这对于新兴开源项目可能很有帮助。对于寻求额外资源来支持自身项目的开发者来说，像 Patreon 这样的工具是一个很好的途径。

一个很棒的桌面应用自述文件

VSCode 无处不在，而且它还有一个很棒的自述文件。

这个自述文件做了很多事情，包括展示 IDE 在使用过程中的样子，这样用户就可以立即了解产品是什么。与 Appsmith 等内部工具开发者相比，这类产品更成熟，更容易为开发者所理解，因此不一定需要更多的可视化效果。VSCode对产品进行了简短、切中要点的描述，并提供了更详细信息的链接。

一个很棒的非产品自述文件

我们还想拿一个更注重教育而不是产品的项目举例。 Trekhleb 的《自制机器学习》就是这样的例子。机器学习学习起来会非常复杂，因此像这样的项目可以得益于良好的可视化效果以及链接。我们发现他们的这个自述文件做得很好，因为里面提供了有关不同机器学习技术的优秀学习资源链接。

这个项目充分利用了可视化效果来帮助学生形成机器学习领域的思维模型，因为这个领域涉及的知识面是相当大的。有很多不同的算法需要学习，但是记住它们之后，就有一种逻辑方法可以对它们进行分类，这张图很好地展示了这一点。

自述文件不仅可以提供最基本的信息，还可以为你的项目提供一个身份

我们希望这篇文章能够为你的项目提供一些思路。除了告诉用户你的项目的用途以外，你的自述文件还设定了大家对其质量和易用性的期望，并且是树立品牌的好方法。

我们对自述文件的内容和结构进行了很多思考，并且发现，每次迭代我们都能够通过调整内容的优先考虑事项来吸引更多的访问者成为用户和社区成员。在制作出更好的自述文件方面，我们永远在路上，而且也没有唯一正确的做法......

译者：boxi。