1、前言

公开项目中，一个好的 README 能帮助我们的公开项目，在 GitHub 上的众多项目和开发人员中脱颖而出；商业项目中，一个好的 README 能帮助部门同事更好理解用途和项目进展。下面我们一起讨论什么是 README 自述文件以及如何编写 README 自述文件。

2、什么是 README 自述文件？

简而言之，大体上有两个定义：

• 可以将 README 文件描述为指南文件，为用户提供项目的详细描述；

• 也可以将 README 文件描述为包含有关如何使用项目的指南的文档，通常包含有关如何安装和运行项目的说明；

作为开发人员，了解如何通过编写 README 来记录您的项目非常重要，因为：

• 这是其他人接触该项目时的第一个文件，因此它应该相当简短但详细；

• 好的 README 文件使得项目脱颖而出；

• README 文件将帮助项目管理，让开发明白项目需要交付什么以及如何交付；

• README 文件能提高你的写作技巧；

3、为什么需要 README 自述文件？

在开发项目业务时，让其他开发人员理解现有的代码及其作用是非常关键的；因此，随附额外的指南将非常有帮助。

在 GitHub 上有这样一个项目，无论它多么令人惊奇，如果没有一个好的 README，其他开发者也不能够第一时间弄清楚它。

举个例子，这个项目的 README，让我们一目了然了解到该项目的作用、它需要什么，以及如果您需要使用该项目或想为该项目做出贡献、如何开始，这就是一个写得很好的 README 的强大之处，以及它如何改变你的项目。

4、如何编写好的 README

需要注意的一件非常重要的事情是，没有一种正确的方法可以构建一个好的 README；但有一种非常错误的方法，那就是根本不包括 README。

一个好的 README 必须有三要素：项目的内容、原因和方式。

以下是一些 checklist，可以帮助我们思路问题：

• 写作动机是什么？

• 为什么建立这个项目？

• 项目解决了什么问题？

• 从项目里学到了什么？

• 项目亮点是什么？

4.1 README 中应包含的内容

4.1.1 项目名称

项目的名称：它用一句话描述了整个项目，并帮助人们理解项目的主要目标和目标是什么。

4.1.2 项目说明

这是许多新开发人员经常忽视的项目的重要组成部分，项目描述是一个极其重要的部分，因为细致的描述可以很好向其他开发人员和潜在雇主展示项目；而通过 README 描述的质量，通常可以区分好项目和坏项目。

我们应该利用好这个机会来解释和展示项目：

• 你的应用程序做什么，

• 为什么你使用你使用的技术，

• 项目面临的一些挑战和你希望在未来实现的功能。

4.1.3 目录（可选）

如果 README 很长，通过添加一个目录会更有条理性，以便用户轻松导航到不同的部分。这将使读者更容易轻松地浏览项目。

4.1.4 如何安装和运行项目

如果项目运行非常依赖于环境或者硬件资源，则应该包括安装项目所需的步骤以及所需的依赖项（如果有），并提供有关如何设置和运行开发环境的分步说明。

4.1.5 如何使用项目

提供项目说明和使用案例，以便用户/贡献者可以使用该项目，这将使他们始终有一个地方可以参考预期的内容。

另外，还可以提供包括屏幕截图等材料，通过视觉辅助工具来显示正在运行的项目的示例以及项目中使用的结构和设计原则。

此外，如果运行项目需要密码或用户名等身份验证，那么请务必补充进去

4.1.6 鸣谢部分

如果你是作为团队或组织参与项目，请列出其他的合作者/团队成员，还要应该包括指向他们的 GitHub 个人资料和社交媒体的链接。

此外，如果项目遵循了教程或参考了可能有助于用户构建该特定项目的特定材料，最好也包含指向这些内容的链接。

虽然这只是表达自己的感激之情的一种方式，但也是为了帮助其他人获得该项目的第一手副本。

4.1.7 添加许可证

对于大多数 README 文件，许可证这块通常被认为是最后一部分，因为它让其他开发人员知道他们可以对您的项目做什么和不能做什么。

根据我们从事的项目类型，我们会有不同类型的许可证可供选择。根据项目选择的许可证，将决定我们项目获得的贡献。

最常见的是 GPL 许可证，它允许其他人修改您的代码并将其用于商业目的。如果我们在选择许可证方面需要帮助，请查看此链接：https ://choosealicense.com/

4.1.8 徽章贡献

徽章不是必需的，但使用它们是让其他开发人员知道您知道自己在做什么的简单方法。

拥有此部分还有助于帮助链接到重要工具，并显示有关我们项目的一些简单统计信息，例如分叉数量、贡献者、未解决的问题等...

下面是一个项目的屏幕截图，显示了如何使用徽章：

这个部分的好处是它会自动更新。

不知道从哪里得到它们？查看shields.io托管的徽章。他们有大量徽章可帮助您入门。你现在可能不明白它们都代表什么，但你迟早会明白的。

4.1.9 如何为项目做出贡献

如果我们正开发一个需要协同开源项目，通过添加指南，让更多人知道如何为项目做出贡献。

同样重要的是要确保为开源项目选择的许可证是正确的，以避免将来发生冲突。而添加贡献指南将起到很大的作用。

一些最常见的指南包括Contributor Covenant和Contributing guide。在为项目设置规则时，这些文档将为项目提供所需的帮助。

4.1.10 测试用例

为项目必要的应用程序编写测试，并提供代码示例以及如何运行它们。

这将有助于表明项目可行性，并避免一些质疑项目的挑战，提高使用者的信心。

4.1.11 README 加分项

在编写 README 时，需要注意以下几点：

• 保持最新 - 确保 README 文件始终是最新的是一个很好的做法。如果有更改，请确保在必要时更新文件。

• 选择一种语言——我们都来自不同的地区，我们都说不同的语言。但这并不意味着需要将代码翻译成白话。用英语编写 README 是可行的，因为英语是全球公认的语言。

4.1.12 合理包装

我们可以给项目添加交互式和信息性指南，并体现出项目的亮点。例如，可以使用许多工具为项目自动生成 README，但在转向自动化之前自行尝试始终是一个好习惯：

• 制作自述文件
  

• 自述生成器
  

• 自述文件