如何为我们的开源项目创建完美的 README？

作者：Rizel Scarlett
译者：前端小智
来源：dev

有梦想，有干货，微信搜索 【大迁世界】 关注这个在凌晨还在刷碗的刷碗智。

本文 GitHub https://github.com/qq449245884/xiaozhi 已收录，有一线大厂面试完整考点、资料以及我的系列文章。

我们正在招聘，年薪：25-60万+奖金，有兴趣的可以点我了解详情。

Hacktober 已经结束了，但这并不意味鼓励程序员为开源做贡献的结束。维护者吸引更多长期贡献者的方法之一是写一个规范的 README。这里，参照一些流行的开源库中的 README 整理了一份清单，让你创建一个能吸引贡献者加入你的社区的 README。

Hacktoberfest 是由知名云服务商 DigitalOcean 发起的一个推广、支持开源的年度在线活动，任何一个开源爱好者都可以参与。只要在10月份内向 GitHub 上的任意开源项目提交若干 Pull Request，就算完成活动任务，并将得到由 DigitalOcean、GitHub 等活动赞助商提供的纪念品。通常是限量版T恤、贴纸若干。

那么，Hacktoberfest 这个奇怪的名字是什么意思呢？这不是一个原生的英文单词，是由几个代表着这个活动的核心精神的单词缩写组合而成。其中的 Hacktober 是由 Hackathon（黑客马拉松） 和 October（十月） fest 则是 Festival（节日）的前几个字幕。看到这里，大家应该就明白了吧， Hacktoberfest 就是开源爱好者在每年的十月份通过做开源贡献的方式来传播、庆祝开源。

我为什么要写 README？

就像找工作要写个人简历一样，为自己的开源项目写一个优秀的 README 同样重要。你README 可以为新用户和潜在贡献者提供了对我们项目的第一印象。说白了，你的 Contributing.md 可以让贡献者在你的版本库中提出和合并拉动请求，而你的 README 则指导用户如何使用你的项目。

我应该在 README 中写些什么？

首先添加项目标题

这个例子来自 Open sauce。

添加一些简短的陈述，描述项目出现原因和作用

这个例子来自Slinkity

告知用户如何安装和使用我们的项目

这个例子来自Timber

让用户知道如何获得帮助

这个例子来自RasaHQ

包括重要文档的链接

这个例子来自CodeNameOne

展示你的贡献者

这个例子来自 use-shopping-cart

添加项目的许可证

这个例子来自 use-shopping-cart

可以附加一点

• 目录(这里有一个关于自动生成目录的文档)
• 项目的技术堆栈和功能
• 已经在用的产品
• 项目的用户界面截图
• 依赖
• 已知的问题

怎么把它弄漂亮点

试试使用Readme.so，这是由Katherine Peterson建立的开源项目，可以轻松建立和定制README的所有部分。

~完，我是刷碗智，励志等退休后，要回家摆地摊的人，我们下期见！

---

---

编辑中可能存在的bug没法实时知道，事后为了解决这些bug,花了大量的时间进行log 调试，这边顺便给大家推荐一个好用的BUG监控工具 Fundebug。

原文：https://dev.to/github/how-to-...

交流

有梦想，有干货，微信搜索 【大迁世界】 关注这个在凌晨还在刷碗的刷碗智。

本文 GitHub https://github.com/qq449245884/xiaozhi 已收录，有一线大厂面试完整考点、资料以及我的系列文章。