还有如果您在用GitHub，这意味着您需要编写一个好的文档来帮助他人了解您的项目。

如果您刚开始使用版本控制，不要失落——这篇指南也是为你准备的。会帮助您学会如何开始写有用的文档。

当我刚开始在GitHub里上传我的项目时，老实说我还没有意识到到底什么是readme文件（即使我经常在他人的项目里看到）。

随着时间的推移我开始关注其他的开发者。他们都拥有很酷的项目并且对开源有所贡献，同时他们有一件事很统一，就是他们的项目都有详尽的 README 文件 。

所以我对一个readme文档怎么发展产生了好奇心，同时我决定尝试并且在我自己的项目中也添加一个。

在这篇文章当中，我们将学习很多关于什么是readme文件以及如何动手编写。

首先，为什么我需要一个好的readme文件？

README文件是给使用者一个对于您上传到仓库的项目做详细描述的说明。

您大概会疑惑为什么要花时间写一个好的README。这里有一些理由来帮助说服您写一个好的readme文件是个好主意：

1. 一个好的README可以帮助您的项目从同类型的其他项目中脱颖而出。它应该像项目本身一样优秀。
2. 当别人访问您的项目时它将会是第一个被看到的文件，所以它应该是简短精炼的。
3. 它会帮助您专注在你的项目需要实现什么以及怎样实现。

就像弗里德里希.尼采所说：
一个好的作者不仅要拥有自己的精神还要有他朋友们的精神。

当编写一个README时，要一直记得您需要让您的朋友或者在这个实例中其他的开发者能理解您的代码。

譬如拿这个来说project。正如您所见，它没有一个详细的README文件，一个说明，或者一个导航。

在github里一个像这样的项目，不管花费多少时间去引用它，都不会有人能理解它的功能，对吗？

现在看一眼这个实例project。这样，您大概能理解这个项目的功能，它的依赖，以及如果您需要使用如何去开始或者对项目改进作出贡献。

看，这就是写好一个README文件的力量。

让我们开始吧

正确编写一个好的README 文件的方式不止一种。但是只有一种非常错误的方法就是项目中完全没有包含一个README文件。

这些步骤是我发现的最佳实践之一。随着您职业生涯的进步，您将有自己的看法，了解什么是好的readme以及如何改进自述。

readme 文件需要回答以下问题：

• 您的动机是什么？
• 为什么您要创建这个项目？
• 它解决了什么问题？
• 通过项目经验您学到了什么？
• 是什么让您的项目脱颖而出？如果你的项目有很多特性，可以考虑添加一个“特性”的部分并在这里列出它们。

怎样编写一个好的readme文件

下面是编写readme文件的步骤。

引入你项目的标题

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

写一个简述

您的简述是您项目的一个非常重要的方面。字斟句酌的简述可以让你向其他开发者以及潜在的雇主展示你的工作。

这是许多新开发者经常忽略的项目重要组成部分。

readme文件简述的质量常常能区分一个项目的好坏。一个好的开发者会利用这个机会来解释和展示：

• 您的应用的作用，
• 您使用某种技术的原因，
• 您面临的一些挑战和还未实现的功能。

一个好的readme文件可以帮助您在众多将项目寄托到github上的开发人员中脱颖而出。

添加目录（可选）

如果你的readme文件很长，可能需要添加一个目录，以方便用户查找所需内容，帮助他们快速导向文件的不同部分。

如何安装您的项目

如果您的项目是需要安装的软件或应用程序，则应包括安装项目所需的步骤。提供如何运行开发环境的手把手教学说明。

怎么使用您的项目

提供说明和示例，以便用户/贡献者可以使用该项目。这将使他们在遇到问题时更容易解决 —— 他们将始终有一个参考。

您还可以引用屏幕截图来显示正在运行的项目示例。

友情链接

如果您作为团队或组织参与项目，请列出您的合作者/团队成员。您还应该引用指向他们的GitHub简介的链接。

此外，如果您引用了其他的辅助项目来构建特定的项目，也请在这里引用指向该项目的链接。这是表达您对引用该项目贡献者感激之情的一种方式，也可以帮助其他人获得该项目的第一手资料。

列出许可

这是大多数readme文件的最后一部分。它让其他开发人员知道他们可以或者不能对您的项目做什么操作。如果您需要选择许可，使用https://choosealicense.com/ 。

🏆 上面列出的部分是良好readme的最低要求。但您可能还需要考虑添加以下部分。

徽章

徽章不是 必须 的。但是使用徽章只是告诉其他开发者你知道你在做什么的一种简单方法。

不知道从哪儿弄来的？查看shields.io托管的徽章. 你可能不明白他们现在都代表什么，但你会及时。

如何为项目做出贡献

如果您创建了一个应用程序或包，并且希望其他开发人员对其做出贡献（一个开源项目），那么您需要添加一些指导原则，让他们知道如何为您的项目做出贡献。

Contributor Covenant 以及The Contributing guide 在制定规则时会给你所需要的帮助。

包括测试

为您的应用程序编写测试。然后提供代码示例以及如何运行它们。

结论

这些就是您写第一篇readme的主要步骤！

现在我们已经完成了这些步骤，我相信您已经准备好为您的项目添加README文件来帮助它们脱颖而出了。

如果您还需要更多的指导，您也可以看看这些实例：

• Make README
• README Generator
• README

也可以查看这个指南navendu-pottekkat

我真的很感激您能读到这里。

可以通过这些途径联系作者Twitter | Insta | YouTube | LinkedIn | GitHub

请分享您的宝贵意见，我很感谢您真诚的反馈！

尽情享受您的编程之旅吧 ❤

原文：How to Write a Good README File for Your GitHub Project，作者：Hillary Nyakundi