如何编写 README 文件 ¹

1. 介绍

1.1. 它是什么？

README 是介绍和解释项目的文本文件。它包含理解项目内容所需的信息。

1.2. 为什么要写？

这是一种简单的方法，可以回答您的受众可能提出的有关如何安装和使用您的项目以及如何与您合作的问题。

1.3. 谁应该写？

任何从事编程项目的人，特别是当你希望其他人使用它或做出贡献时。

1.4. 什么时候写？

在向其他人展示或公开你的项目之前，一定要这样做。你可能需要养成将其作为 新项目中创建的第一个文件² 的习惯。

touch README.md

1.5. 放在哪里？

在项目的顶层目录中。这是项目新手的起点。GitHub、Bitbucket 和 GitLab 等代码托管服务也会查找您的 README 文件，并将其与项目中的文件和目录列表一起显示。

1.6. 如何写？

虽然 README 可以用任何文本文件格式编写，但如今最常用的是 Markdown 格式。它允许你添加一些轻量级的格式。你可以在 CommonMark 网站上了解更多信息，该网站还提供了一份实用的参考指南和一份交互式教程。

您可以使用任何文本编辑器。许多编辑器（例如 Atom、Emacs、Sublime Text、Vim 和 Visual Studio Code ）都提供插件，允许您在编辑 Markdown 时进行预览。

您还可以使用专用的 Markdown 编辑器（例如 Typora）或在线编辑器（例如 StackEdit 或 Dillinger）。

2. 编写建议

每个项目都有所不同，因此请考虑以下哪些部分适用于您的项目。模板中使用的部分适用于大多数开源项目。另外请记住，虽然 README 可以太长太详细，但长总比短好。如果您认为 README 太长，请考虑使用其他形式的文档，而不是删减信息。

2.1. 名称

为您的项目选择一个不言自明的名称。

2.2. 描述

让人们了解您的项目具体能做什么。提供背景信息，并添加访客可能不熟悉的参考链接。您还可以在此处添加 “功能” 列表或 “背景” 子部分。如果您的项目有替代方案，这里是列出差异化因素的好地方。

2.3. 徽章

在某些 README 中，您可能会看到一些小图像，用于传达元数据，例如项目的所有测试是否都已通过。您可以使用 Shields 将一些信息添加到 README 中。许多服务还提供添加徽章的说明。

2.4. 视觉效果

根据你正在制作的内容，添加截图甚至视频是个不错的主意（你经常会看到 GIF 动图而不是实际的视频）。ttygif 之类的工具可以提供帮助，但 Asciinema 提供了更复杂的方法。

2.5. 安装

在特定的生态系统中，可能存在一些常用的安装方式，例如使用 Yarn、NuGet 或 Homebrew 。但是，请考虑阅读 README 的用户可能是新手，他们可能希望获得更多指导。列出具体的步骤有助于消除歧义，并帮助用户尽快上手使用您的项目。如果项目仅在特定环境中运行（例如特定的编程语言版本或操作系统），或者需要手动安装依赖项，请同时添加 “需求” 子部分。

2.6. 用法

尽量使用示例，并尽可能展示预期输出。最好内联一个能够演示的最小用法示例，如果示例过长，无法合理地包含在 README 文件中，则应提供更复杂示例的链接。

2.7. 支持

告诉人们在哪里可以寻求帮助。可以是问题跟踪器、聊天室、电子邮件地址等的任意组合。

2.8. 线路图

如果您对将来的发布有想法，最好将其列在 README 中。

2.9. 贡献

说明您是否愿意接受捐助以及接受捐助的要求是什么。

对于想要修改项目的人来说，准备一些入门文档会很有帮助。比如，他们需要运行一个脚本，或者设置一些环境变量。请明确说明这些步骤。这些说明对未来的你来说也可能有用。

您还可以记录用于 lint 代码或运行测试的命令。这些步骤有助于确保代码高质量，并降低更改无意中造成破坏的可能性。如果需要外部设置（例如，在浏览器中启动 Selenium 服务器进行测试），那么提供运行测试的说明会特别有用。

2.10. 作者和致谢

向那些为该项目做出贡献的人表示感谢。

2.11. 许可证

对于开源项目，说明它是如何获得许可的。

2.12. 项目状态

如果您在项目中已经耗尽精力或时间，请在 README 文件的顶部添加注释，说明开发进度已放缓或完全停止。有人可能会选择 fork 您的项目，或自愿加入成为维护者或所有者，让您的项目继续运行。您也可以明确请求维护者。

3. 模板

以下是一些模板，您可以使用它们作为起点。您可以根据需要进行修改。

# Foobar

Foobar is a Python library for dealing with word pluralization.

## Installation

Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.

```bash
pip install foobar
```

## Usage

```python
import foobar

# returns 'words'
foobar.pluralize('word')

# returns 'geese'
foobar.pluralize('goose')

# returns 'phenomenon'
foobar.singularize('phenomena')
```

## Contributing

Pull requests are welcome. For major changes, please open an issue first
to discuss what you would like to change.

Please make sure to update tests as appropriate.

## License

[MIT](https://choosealicense.com/licenses/mit/)

4. FAQ

是否有标准的 README 格式？

这里的建议并不适用于每个项目，因此 README 中应包含哪些信息实际上取决于开发人员。

关于编写 README 还有什么其他想法？

查看 Awesome README 以获取更多资源列表。

README 文件应该命名为什么？

README.md （如果您选择使用非 Markdown 文件格式，则可以使用其他文件扩展名）。它通常大写，以便更突出，但如果您认为小写更好看，也没关系。

如何编写 README 文件 1