运营一个开源项目就像在运营着一家 Startup,你期待更多人来使用你的项目,并给你的项目加 Star/提交 PR,但好的项目除了其自身真正契合了开发者的需求外,还须要一个好的 README。html
有好的 README 文档的项目不必定是一个好开源项目,但一个好开源项目必定有一个好的 README。git
目前 README 文档编写并无规范,但一个友好的 README 是有其特征的,咱们来看看一个好的 README 的必备要素。程序员
首先要注意的是国际化问题,若是你但愿本身的项目能得到更多人的使用,提供中英两种 README 文档是很是赞的。你能够在项目头部注明它。如 Coding 的 WebIDE 项目:github
好的项目名及简介是好项目必不可少的。开源项目名不宜过长(除非你有特别的理由这么作),若是你不知道如何给本身的项目起名,可使用 随机项目名产生器(适用于 Javascript 项目);项目简介能够是简单的几句话,但项目简介要说明几个你的开源项目用户想迫切了解的问题,这包括:web
如 Coding 的 WebIDE 项目:segmentfault
此外你还能够给项目增长一些图标以提升可读性,推荐使用 Shields.iomarkdown
你还能够将项目 Logo(若是有的话)放置在 REAME 顶部(这里推荐一个在线制做 Logo 的网站 Canva ),项目截图(Gif 动图更佳)也能够帮助你的用户更快速更直观地了解你的开源项目。架构
你能够注明这个项目的功能特色,亮点特点会大大提升访客使用这个项目的几率。app
如 Coding 的 WebIDE 项目。ide
这是 README 中最重要的部分,你须要说明这个项目如何使用,这包括:
对于一个开源项目来讲,令其做者最开心的莫过于有人提交 Pull Request 了。加入一个 CONTRIBUTING 文档将大大提升他人贡献你的项目的几率。
你能够说明你的代码规范,项目架构,如何测试和提交 Pull Request 的正确格式,以及其余有利于开发者进行贡献的信息,这将会使你的项目变得更加的规整如一。你能够在项目根目录新建一个 CONTRIBUTING 进行详细的说明并在 README 中添加其文件锚连接。如 Google 的 Template:
版权是很是重要的,若是没有声明版权,不少用户特别是企业级用户将受制于法律问题,没法使用你的项目。关于如何选择开源项目许可证,推荐阅读这篇文章:《如何选择开源许可证?》
如 Coding 开源的 帮助文档 版权:
你还能够感谢直接或间接为这个项目作出贡献的人、项目。
如 ttyd 项目:
咱们推荐使用 Markdown 编写你的 README,请最好注意排版问题以增长文档可读性,推荐阅读 Coding 的 《文案排版规范》。
这就是一个好的 README 所需元素了,固然你还能够增长其余任何利于开发者的信息如 Roadmap 等等,这因项目而异。如今,去完善你的开源项目信息或开始作一个开源项目吧!
一些建议:选择一个好的代码托管平台/社区可让你的开源项目得到更多曝光,你能够在 Coding 的 冒泡社区(能够理解为程序员的朋友圈)发布你的项目简介,截图和地址,与 30 万中国开发者分享你的开源项目;另外咱们推荐同时 push 项目到 Coding 和 GitHub(可参考 该回答 ),得益于 Coding 遍及全国的 CDN,国内用户 clone 你的项目时的速度将大大提高。
Happy Coding ; )
(完)
你可能会感兴趣的文章: