如何写好 README

README 文件是一站式文档文件。通常，它不仅是任何人首次接触你的项目时阅读的第一个文件，也是你的重复访问者的关键文档。

为什么 README 很重要？

几周前，我不得不在电脑上安装一个开源项目。这是我第一次与该项目互动，体验非常糟糕，本来只需要一两个小时就能完成的事情，却花了我两天时间。之所以花了这么长时间，主要原因是该项目的 README 文件有待改进，以便帮助新接触该项目的开发人员更好地进行首次交互。

在自己的项目中集成和使用开源解决方案、库或工具是许多开发者的日常工作，而 README 文件无疑是这项任务的起点。因此，一份优秀的 README 文件对于开源项目来说，与代码质量一样重要。

你的听众是谁？

在深入探讨什么是好的内容以及如何编写 README 文件之前，让我们先深入了解一下谁将阅读该文档。

要写好 README 文件，关键之一就是要考虑读者。这个文件是写给谁看的？你的读者是谁？在这方面，我喜欢把它们分为三类。

1. 最终用户。他们是应用程序的实际用户。他们也可能是寻求解决方案的业务分析师。他们可能缺乏深厚的技术知识，更关心解决方案的功能性，而非技术实现。

2. 技术用户。这些人拥有技术背景，会在自己的环境中安装或设置项目。你也可以将他们视为某种集成商。他们会将你的项目集成到他们正在进行的项目中。他们关心技术方面，但就像用户一样，他们不太关心项目是如何实现的，而是更关心项目提供的功能。例如，如果你的项目公开了一个 API 或是一个库，他们想使用这个 API/库，但他们对了解所有实现细节并不感兴趣。

   请注意，根据项目类型的不同，有时最终用户和技术用户可能是相同的目标受众。例如，如果您的项目是一个 JavaScript 库（例如 React JS），那么您的最终用户大多数情况下也是技术用户，即开发者。但是，如果您的仓库是一个 iOS 应用程序，那么您的最终用户（拥有 iPhone 并使用 App Store 的用户）不一定与您的技术用户（想要使用 Xcode 安装应用程序的用户）相同。

3. 贡献者。他们是您将与之进行某种程度互动的人，因为他们对您的项目的参与程度更高。例如，贡献者可以是需要支持来安装解决方案的技术用户，可以是想要报告错误或建议新功能的人，可以是想要提交带有增强功能的拉取请求的人，也可以是想要在经济上支持项目的人。如您所见，这是最多元化的群体，但将他们全部纳入一个群体可以使事情变得简单。

README 格式和写作风格

虽然 README 文件是纯文本文件，但因为大多数源代码托管平台（例如Github、GitLab或Azure Repos）都支持Markdown 格式，所以你在外面看到的大多数 README 文件都是使用Markdown 语法编写的。

这种文本格式非常简单，但功能丰富，输出效果也相当不错。它支持标题、粗体、斜体、项目符号列表、编号列表、代码块、链接等。事实上，这篇博文也是用 Markdown 编写的。

Markdown 的简单示例：

# Heading 1

Preprending a `#` at the beginning of the first 
line of a paragraph converts it into a heading 
1 (biggest font heading).

## Heading 2

Two `#` is for heading 2. And so on so forth till 6.

To set a text in *bold* just enclose it 
in asterisks. For _italic_ use the underscore. 

Markdown also supports [links](http:/dev.to/merlos)

根据“人们不阅读，他们扫描”这一公理，正确使用 Markdown 将允许您为文档提供一些可视化结构并帮助用户扫描文件的内容。

通过设置结构（使用标题、列表、段落），您可以帮助您的用户快速找到他们正在寻找的信息。

例如，一位开发人员在回家的地铁上发现了你的项目，因为他当时正在打电话，所以他给它加了星标，几天后又回来安装了它。几周后，他发现了一个 bug，想报告它。通过在 README 中添加标题（也就是结构），他就能更容易地找到他感兴趣的特定部分。

此外，为了使文本适应我们在线阅读的方式，即扫描、搜索关键词等，您可以遵循一些网络写作的基本原则，如下所示：

1. 使用短段落。使用大约3到5行是一个很好的经验法则。每段应该只包含一个概念。这将有助于阅读。

2. 使用项目符号或编号列表，而不是逗号分隔的列表。此基本规则列表仅供参考。这同样有助于浏览。

3. 永远不要使用click here“点击此处”作为链接，而要使用一些有意义的文字。除其他原因外，使用“点击此处”会迫使用户阅读链接周围的上下文，而更合适的文字会向读者解释为什么你永远不应该使用“点击此处”。

4. 用粗体突出显示关键词或句子段落。避免使用下划线，因为它可能会与链接混淆。

5. 每一段都以最重要的信息开头。写作时使用倒金字塔结构**。从对读者最重要的内容开始，然后再提供其他细节。

自述文件内容

好的，现在我们知道了我们为谁写作以及如何为文件提供结构和形式的良好做法，让我们看看 README 的一些建议内容。

这里介绍的结构遵循与您的项目交互的自然方式：

1. 首先我们将简单解释一下这个项目的内容，
2. 然后，我们将继续介绍如何安装以及如何开始使用它，
3. 最后，我们将为读者提供如何参与、如何合作。

此结构遵循您项目的参与程度，涵盖我们列出的每类用户的预期。最终用户只是想了解项目。

请注意，某些部分可能并不特别适合您的项目，或者您可能希望以不同的方式标记它们，但无论如何，上述三级结构肯定适用。

让我们从以下部分开始：

概述

这里你需要简单介绍一下你的项目。不要超过两三段。想想你需要向第一次接触你项目的人传达什么。这部分的主要受众是你的最终用户。

在这个简短的介绍之后，您可以为那些有兴趣了解更多有关您的项目的人提供网站、维基页面的链接，并提供进一步的解释和/或演示。

最后，如果不太明显，你可能需要列出一些你正在使用或支持的技术、框架。这些信息对于需要评估其是否适合其项目或组织架构的技术用户来说可能很有用。

以下是 React JS 项目的示例（使用 Markdown）

React is a JavaScript library for building user interfaces.

1. Declarative: React makes it painless to create interactive UIs. Design simple views for each state in your application, and React will efficiently update and render just the right components when your data changes. Declarative views make your code more predictable, simpler to understand, and easier to debug.
2. Component-Based: Build encapsulated components that manage their own state, then compose them to make complex UIs. Since component logic is written in JavaScript instead of templates, you can easily pass rich data through your app and keep the state out of the DOM.
3. Learn Once, Write Anywhere: We don't make assumptions about the rest of your technology stack, so you can develop new features in React without rewriting existing code. React can also render on the server using Node and power mobile apps using [React Native]().

[Learn how to use React in your project]().

如你所见，首先展示的是项目，最后会显示一个链接，方便你了解更多信息。在这种情况下，主要受众是开发人员，因此最终用户和技术用户是相同的。

安装

此时，您已经获得了 README 读者的足够关注，因此他想要更进一步尝试一下。

这里你需要展示安装步骤。例如，对于 NodeJS 应用程序，通常你会指示如下内容：

git clone http://url-to-my-repo
npm install
npm start

或者对于 Python 库

pip install your-library-name

等等。

专业提示：在 Markdown 中，你可以用三个撇号括起代码块。如果你在第一组撇号后添加语言名称（例如ruby, javascript, typescript, swift, bash），渲染时就会应用语法高亮。

例如：

呈现为：

    // This is my Javascript code
    if (a > b) return true;

请注意，在这种情况下，您假设读者已在其系统上安装了包管理器npm或pip，但事实可能并非如此。因此，在尝试安装项目之前，请考虑指定所需的先决条件。只需提供每个先决条件的安装页面链接，即可为读者提供很大的帮助。在上面的 NodeJS 示例中：

To install this application you need 

  (Node JS 16.0 or above)[https://nodejs.org/en/download/]

使用方法/入门

现在读者已经将您的项目纳入他的系统中，现在是时候展示他借助您的成果所能实现的超能力了。

在开始时，您可以内联包含一些基本说明或指向更丰富的文档。

目标是指导读者在他的环境中安装您的项目后该做什么。

文档

除了基本的入门步骤/入门指南外，读者可能还想深入了解项目的所有功能。这可能取决于项目的类型：

• 对于应用程序，它可能描述如何使用它、选项、如何针对不同的用例进行设置。
• 对于库、框架，它可能描述 API、方法、类或一些高级示例。

您可能会考虑的一些其他文档包括：

• 部署最佳实践。如何在生产环境中部署。
• 安全指南。如何强化任何安装以避免任何网络安全问题。
• 故障排除。
• ETC。

根据您构建文档和自述文件的方式，您可以将此部分与入门部分合并。

发展

从现在开始，本节及后续章节将面向那些深入了解您项目细节或希望成为社区活跃成员的读者。在潜在读者的分类中，我们称之为贡献者。

本开发部分介绍如何在开发模式下设置环境。您需要哪些工具，以及如何在调试模式下运行项目、运行单元测试等。

# Example of running the automated unit test suite

npm test

贡献

本节旨在为想要真正做出贡献的读者提供任何附加信息。

• 如何报告错误
• 行为守则
• 编码风格指南
• 如何创建拉取请求 (PR)
• 如何获得支持
• 如何捐款
• 如何联系商业支持
• ETC。

您可能希望将部分文档添加到单独的文件中。例如，GitHub 允许您设置CODE_OF_CONDUCT.md和其他文件。

致谢

承认那些给你的工作带来启发的人（其他 repos、其他项目）或提及项目的关键贡献者（即那些添加了新功能、提交了拉取请求、修复了错误等的人）是一种很好的做法。

执照

README 的最后一部分通常保留版权和许可。

虽然乍一看，您可能认为这并不重要，但事实是，设置许可证是关键，因为它可以帮助其他开发人员了解软件使用的限制。

这里列出了一些开源许可证。您应该对每个许可证的含义有一个大致的了解。我个人通常会在 GPL3 和 MIT 之间进行选择。

1. MIT是最简单的许可证，它的意思大致是：你可以用这段代码做任何你想做的事情。风险自负，而且不适合我。

2. GPL是一种版权左派许可证。它比 MIT 许可证限制性更强，因为它强制要求任何贡献或定制的代码都必须公开发布，并且必须遵循 GPL 许可证进行分发。GPL 对于商业用途的吸引力较小，但对整个社区来说更有利，因为任何贡献都会回馈给社区。例如，GNU/Linux 内核就是遵循此许可证分发的。

在 README 的这一部分中，您不需要添加许可证的全部文本，只需添加横幅，但通常，您应该在文件LICENSE或中包含整个许可证的副本LICENSE.md。

额外的球

您可以添加到项目自述文件中的一些内容是图像和状态徽章。

图片

如前所述，README 文件通常用 Markdown 编写。这种语言允许你在其中链接图像，这些图像将在 Markdown 渲染后显示出来。

特别是在两种情况下这可能有用：

1. 让它看起来更酷。例如，在 readme 开头添加一个 logo，让它看起来更棒。这会给人留下良好的第一印象。

2. 展示/提供演示。一张图片胜过千言万语。您可以录制一个简单的 GIF 动图，展示项目的主要功能，帮助读者轻松理解项目内容。

状态徽章

另一个可以在 README 文件中添加的“酷”功能是状态标记。状态标记会显示代码库中某个特定方面的状态，例如单元测试是否通过、流水线是否正常运行、最新发布的版本号、代码覆盖率等等。

它向您的访问者简要地展示项目的一些指标。

您可以检查徽章/盾牌仓库以向您的项目添加一些徽章。

在 README 中使用图像和徽章的唯一缺点是它们不会在简单的文本编辑器中呈现，但您可以忽略它，因为大多数情况下该文件将显示在 repo 网站或通常支持 Markdown 渲染的开发人员友好编辑器中。

概括

如果您正在参与开源项目， README 文件是可以提升开发人员体验的关键一站式文档。

要写好自述文件，您需要记住阅读该文件的受众类型：最终用户、技术用户和贡献者。

您应该注意人们如何在网络上阅读，帮助他们使用 Markdown 扫描您的 README，以及网络写作的良好做法，例如短段落、列表和倒金字塔写作模式。

README 的内容应遵循以下结构：首先介绍项目，然后解释如何安装和使用它，最后解释如何作为贡献者参与项目。

希望你喜欢这篇文章。最后一个问题：你最喜欢的或者最好的 README 文件是什么？