文档 101：为你的软件项目创建一个好的 README

为您的开源项目提供良好的文档是一项重要（且经常被忽视）的功能，它可以推动采用并展示用户使用您的应用程序或库所能实现的全部潜力。

不幸的是，文档的增长速度通常比代码慢得多，主要是因为一些看似简单的实现可能会衍生出大量可能的用例以及应用程序或库中某些操作的变体。涵盖所有可能的场景是不可能的，因此技术文档撰写者的首要任务是确定范围和优先级。专注于那些必须首先记录下来以支持最常见用例的必要知识至关重要。

本文是《初学者软件文档》系列文章的第 1 部分，我将分享一些为您的项目构建良好 README 文件的技巧。

自述文件

项目的 README 文件通常是用户与项目的第一个接触点，因为用户进入项目代码库时首先看到的就是它。因此，优先考虑一份优秀的 README 文件作为项目文档的起点至关重要。

以下是我们今天要讨论的内容的概要：

• 1. README 大小（少即是多）
• 2. 将 README 拆分成其他文档
• 3. 基本信息
• 4. 使用徽章

当然，不同的项目在 README 中展示的内容不同，但这些技巧应该可以作为大多数软件项目的良好起点。

1. 少即是多

您可能想将所有内容都放在 README 中，例如如何安装和使用项目、如何部署、如何调试……但 README 应该更像一个入口点，您可以在其中分享最重要的信息和更完整文档的链接，以更详细地介绍这些主题。

当然，刚开始的时候，只写 README 就足够了。但是，过长的 README 缺乏吸引力，由于没有目录或导航菜单，查找信息会更加困难，最终会影响良好的用户体验。简短的 README，加上相关资源的链接，可以让项目看起来更有条理，也更简洁。

如果我不想为这个项目创建专门的文档网站怎么办？在这种情况下，您可以考虑docs在项目根目录中创建一个文件夹，用于保存其他 Markdown 文档，以便直接从代码托管平台（假设是 GitHub）浏览。

2. 将 README 拆分成其他文档

对于仓库内文档，您可以/docs在应用程序的根目录中创建一个目录，并使用/docs/README.md文件作为文档的入口点或索引。

此文件夹的内容创意：

• installation.md - 详细说明如何安装项目的文档。
• usage.md——项目使用情况和主要命令的更详细视图。
• advanced.md - 包含一些高级使用选项和用例的文档。

这些只是一些可以作为起点的想法。如果您觉得需要创建包含子文件夹的更复杂的结构，则应该认真考虑为您的项目创建一个专门的文档网站（我们将在本系列的后续文章中介绍）。

3. README 要点

以下是您 README 中绝对应该包含的一些内容：

• 项目的高层概述，包括编写的语言、功能以及用途；
• 项目要求；
• 安装文档的链接；
• 使用概述，让用户简要了解如何执行；
• 故障排除或调试提示（可以链接到单独的文档）；
• 链接到其他资源以了解更多信息。

理想情况下，这些应该是简短的说明，并在必要时链接到更全面的文档。

根据项目的规模和目标，您应该考虑在其中添加其他内容：

• 指向 CONTRIBUTING.md 文档的链接，其中包含有关用户如何为您的项目做出贡献的详细信息（如果项目是开源的）
• 包含项目行为准则的 CODE_OF_CONDUCT.md 文档的链接。

如果您的项目托管在 GitHub 上，这些内容将突出显示在项目页面右侧边栏的“关于”部分正下方。

示例结构

以下是 Markdown 中的一般结构，您可以将其用作构建项目 README 的基础：

# Project Name

A paragraph containing a high-level description of the project, main features and remarks.

## Requirements

Here you should give a general idea of what a user will need in order to use your library or application. List requirements and then link to another resource with detailed installation or setup instructions.

- Requirement one
- Another requirement

Check the [installation notes]() for more details on how to install the project.

## Usage

Include here a few examples of commands you can run and what they do. Finally link out to a resource to learn more (next paragraph).

For more details, check the [getting started guide]().

## Useful Resources

Include here any other links that are relevant for the project, such as more docs, tutorials, and demos.

4. 使用徽章

您可以使用徽章来丰富您的自述文件，其中包含从项目自动提取的快速信息，例如最新版本的状态、最新的稳定发布版本、项目许可证等。

有多种服务为开源项目提供徽章。正如@mohsin在本文评论区指出的那样，你可以直接从 GitHub Actions 获取徽章，方法是：进入你的工作流程页面，点击右上角显示的三个点，然后从菜单中选择“创建状态徽章”。

这将向您显示一个带有 markdown 代码的对话框，您可以将其复制并粘贴到您的 README 文件中。

另一个不错的选择是使用Shields.io网站，它提供了几种不同的徽章，您可以在开源项目中免费使用。

例如，这是显示yamldocs最新版本的图像 URL ：

https://img.shields.io/github/v/release/erikaheidi/yamldocs?sort=semver&style=for-the-badge

这将生成以下徽章，显示最新的发布版本：

以下是带有多个徽章的 README 示例：

结论

文档是任何软件项目的重要组成部分，从一开始就应该认真对待。最好的方法是创建一个好的 README 文件，向用户展示必要的信息，而不是让他们被那些在开始使用项目时可能不需要的内容淹没。

在本系列的下一篇文章中，我们将讨论其他类型的文档，以及当您决定是时候拥有一个专门的文档网站时可以在哪里托管您的文档。