自述文件模板如何编写出色的自述文件

可以说，任何开源项目最重要的文档就是 README 文件。一份好的 README 文件不仅能告诉人们这个项目的功能和目标用户，还能告诉人们如何使用和贡献项目。

如果您编写的自述文件没有足够的解释您的项目的作用或人们如何使用它，那么它几乎违背了开源的目的，因为其他开发人员不太可能参与或为其做出贡献。

TL;DR - 太长？跳到最后并使用我的模板。

什么是自述文件？

本质上，README 是一个单一的文本文件（.txt或.md），作为项目或目录的一站式文档。它通常是大多数开源项目最显眼的文档和落地页。即使 README 文件名全部大写，也是为了吸引读者的注意力，确保它是他们首先阅读的内容。

有证据表明，README 可以追溯到 20 世纪 70 年代。我能找到的最古老的例子是DEC PDP-10 计算机的README，日期是 1974 年 11 月 27 日。虽然 README 这个名字的起源存在争议，但最流行的两种说法是：

1. 最初使用穿孔卡的大型计算机的程序员会留下一叠纸质说明，正面写着“请阅读！”。

2. 这个名字是对刘易斯·卡罗尔的《爱丽丝梦游仙境》的致敬，书中的主角爱丽丝发现了一瓶标有“喝我”的药水和一蛋糕标有“吃我”，这使她的大小发生了变化。

您应该在 README 中包含哪些内容？

那么，一份优秀的 README 文件应该包含哪些内容呢？首先，我建议你包含以下关键内容：

1. 命名
别忘了给你的项目或功能命名。GitHub 上有很多项目都没有名字，数量惊人。

2. 简介或总结
写一个两三行的简短介绍，解释你的项目用途和目标用户。不要使用“简介”、“总结”或“概述”之类的标题——这显然是一篇简介。

3. 先决条件
在你的介绍之后立即添加一个部分，列出任何想要使用该项目的人在开始之前可能需要的先决知识或工具。例如，如果它在最新版本的 Python 上运行，请告诉他们安装 Python。以下是一个例子：

Prerequisites

Before you continue, ensure you have met the following requirements:

* You have installed the latest version of Ruby.
* You are using a Linux or Mac OS machine. Windows is not currently supported.
* You have a basic understanding of graph theory.

4. 如何安装
？提供安装步骤！我遇到过很多项目，它们只提供基本的使用说明，并指望你能够神奇地学会如何安装，这真是令人惊讶。如果安装过程需要多个步骤，请务必将其分解成几个按编号排列的步骤。

5. 如何使用该项目
：添加用户安装后如何使用该项目的步骤。如果您认为示例和参考信息有用，请务必提供解释命令选项或标志的说明。如果您在单独的文件或网站中有更高级的文档，请从此处链接至此。

6. 如何为项目做出贡献
提供为项目做出贡献的步骤。或者，如果您希望人们在向您的项目提交拉取请求之前阅读贡献者指南，您可以创建一个单独的文件，并在 README 中添加指向该指南的链接。

7. 添加贡献者
在作者部分中，对所有为项目提供帮助的贡献者进行致谢。这是一个很好的方式，可以让开源项目看起来像是一个团队合作，并感谢每一位付出时间做出贡献的人。

8. 添加致谢
同样，如果您使用了其他人的作品（代码、设计、图像等），而这些作品的版权需要致谢，您也可以在此处添加。您还可以致谢任何为该项目提供帮助的其他开发者或机构。

9. 联系信息
如果您是一个非常注重隐私的人，您可能不想这样做，但如果有人有疑问、想与您合作或对您的项目印象深刻并愿意为您提供工作机会，那么将您的联系方式放在显眼的位置是有意义的。

10. 添加许可证信息。
如果适用，请务必添加许可证信息。除非您提供这些信息，否则依赖第三方软件的初创公司和其他公司不太可能使用您的项目。请访问choosealicense.com或opensource.org获取您可能可以使用的许可证列表。

为你的 README 增添光彩🔥

如果你真的想让你的 README 脱颖而出并且看起来具有视觉吸引力，你可以执行以下操作：

• 添加徽标：如果您的项目有徽标，请将其添加到 README 的顶部。品牌标识可以使项目看起来更专业，并帮助人们记住它。

• 添加徽章或盾牌：您可以添加徽章和盾牌来反映项目的当前状态、使用的许可证以及依赖项是否为最新版本。而且它们看起来非常酷炫！您可以在Shields.io上查看徽章列表或设计您自己的徽章。

• 添加屏幕截图：有时，一张或一组简单的屏幕截图就能传达出远超千言万语的信息。但请注意，如果您使用屏幕截图，则每次更新项目时都需要更新它们。

• 使用表情符号？：现在很多项目似乎都在使用表情符号，不过是否使用完全取决于你自己。表情符号可以为你的 README 文件增添一些色彩和幽默感，让项目更具人性化。

如果您使用“所有贡献者”来确认贡献，则可以使用他们的表情符号键来表示不同的贡献类型：

* 🐛 for raising a bug
* 💻 for submitting code
* 📖 for docs contributions etc.

以下是 GitHub 徽章或盾牌的外观，仅供参考（毫无疑问您之前见过它们！）：

我的模板

我创建了一个模板，涵盖了本文中提出的大部分建议。欢迎您 fork 该代码库，提出改进建议，或根据您自己的需求进行自定义！您可以在 GitHub 上找到我的模板。

资源

如果您需要有关 README 的更多建议，我还推荐以下资源：

• 丹尼尔·贝克 (Daniel Beck)在 2016 年的“编写文档”中发表了题为“编写可读内容”的演讲。

• Lorna Jane Mitchell在 API Docs 2019 上发表的演讲“Github 作为登陆页面” 。

• 查看 Franck Abgrall 的README 生成器。