如何编写开源项目的 README 文档
运营一个开源项目就像在运营着一家 Startup,你期待更多人来使用你的项目,并给你的项目加 Star/提交 PR,但好的项目除了其自身真正契合了开发者的需求外,还需要一个好的 README。
有好的 README 文档的项目不一定是一个好开源项目,但一个好开源项目一定有一个好的 README。
目前 README 文档编写并没有规范,但一个友好的 README 是有其特征的,我们来看看一个好的 README 的必备要素。
国际化问题
首先要注意的是国际化问题,如果你希望自己的项目能获得更多人的使用,提供中英两种 README 文档是非常赞的。你可以在项目头部注明它。如 Coding 的 WebIDE 项目:
项目名及简介
好的项目名及简介是好项目必不可少的。开源项目名不宜过长(除非你有特别的理由这么做),如果你不知道如何给自己的项目起名,可以使用 随机项目名产生器(适用于 Javascript 项目);项目简介可以是简单的几句话,但项目简介要说明几个你的开源项目用户想迫切了解的问题,这包括:
这个开源项目是做什么的?
这个项目是什么语言编写的?
项目维护、CI、依赖更新状态(如果有)
项目可用版本及其他版本
Demo 或官网地址(如果有)
如 Coding 的 WebIDE 项目:
此外你还可以给项目增加一些图标以提高可读性,推荐使用 Shields.io
项目 Logo 和使用截图
你还可以将项目 Logo(如果有的话)放置在 REAME 顶部(这里推荐一个在线制作 Logo 的网站 Canva ),项目截图(Gif 动图更佳)也可以帮助你的用户更快速更直观地了解你的开源项目。
功能
你可以注明这个项目的功能特点,亮点特色会大大提高访客使用这个项目的概率。
如 Coding 的 WebIDE 项目。
用法
这是 README 中最重要的部分,你需要说明这个项目如何使用,这包括:
如何下载这个项目:一般情况下 git clone 该项目地址即可,当然你也可以提供其他包管理下载安装方式;
项目依赖:你需要说明编译运行这个项目前需要哪些依赖;
安装:你需要说明如何编译安装/运行这个项目;
部署:如果这个项目可以部署的话,请最好注明部署要注意的事项;
Debug 方法:理想状况下,你的用户会顺利编译并运行这个项目,但你要确保用户遇到了问题不会来打扰你(如提交 Issues),你还需要提供用户可能会遇到的常见问题;
贡献
对于一个开源项目来说,令其作者最开心的莫过于有人提交 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 ; )
(完)
你可能会感兴趣的文章:
《Coding 如何使用 Coding 开发 Coding》
《使用 Feature Branch Workflow 让开发更简单》
《使用原理视角看 Git》
如何编写开源项目的 README 文档相关推荐
- 如何生成项目的chm文档
如何生成项目的chm文档 2014-11-30 Generate .chm based documentation of your project using SandCastle tool 转载于 ...
- Maven学习总结(43)——利用javadoc插件生成项目的API文档
在进行Java学习的时候,相信大家都看过在线或者下载的java api文档,可能是html格式或者chm格式的,其实这些参考文档也是很容易生成的,这里介绍一个maven的插件来实现项目代码文档的生成. ...
- SpringCloud微服务项目的api文档聚合
目录 原理简介 在网关中配置好路由 Spring Cloud Gatway + Springfox 第一步.在各项目里配置Springfox 第二步.在网关中编写api文档资源路径 注意 Spring ...
- idea的springboot项目的xml文档中查询语句有黄色背景
接下来介绍如何不显示黄色背景的方法: 1.File -- Settings (或者Ctrl + Alt + S 快捷键)打开设置界面: 2.然后找到 Editor -- Inspections : 3 ...
- README文档的规范写法
看过很多开源库,发现有些库的文档写的一团糟,有的甚至就是一个标题,让你自己下载之后运行,自己摸索,看的很头疼.而那些使用量大的库的文档写的很标准,很详细,看的很舒服. README文档写的好的话能减少 ...
- 第十五章 如何编写README文档
README 文档对于开源项目的重要性甚至会超过代码本身.你试想一下,你打开一个 Github 项目,第一时间就会看到 README 文档,而这时候同一类的项目你可能有很多选择,如果这个README不 ...
- 参与 Apache 顶级开源项目的 N 种方式,Apache Dubbo Samples SIG 成立!
头图来源:https://opensource.guide/ 来源 | 阿里巴巴云原生公众号 只有贡献代码才算是参与开源项目社区贡献吗? 一说到参与开源项目贡献,一般大家的反应都是代码级别的贡献, ...
- 参与Apache顶级开源项目的N种方式,Apache Dubbo Samples SIG 成立!
简介:一说到参与开源项目贡献,一般大家的反应都是代码级别的贡献,总觉得我的代码被社区合并了,我才算一个贡献者,这是一个常见的错误认知.其实,在一个开源社区中有非常多的角色是 non-code cont ...
- 软件测试质量过程检测文档_如何编写实际上有效的质量检查文档
软件测试质量过程检测文档 A software product is like an airplane: it must undergo a technical check before launch ...
- 如何写一个优秀的GitHub项目README文档?
今天给大家介绍一个Github上的README文档写作教程模版,该模版目前获得6634颗星星,2296Fork,相对而言,还是比较得到大家认可的.不花哨,不别出心裁,一个比较实用的,普适性的架子:所谓 ...
最新文章
- go context之WithDeadline的使用
- [文摘20080919]小软件将网页变为3D世界
- iphone屏蔽系统更新_屏蔽 iOS 系统更新的最新方法,支持所有 iPhone、iPad 设备
- AJAX淋漓尽致的发挥(Google个性化主页 VS. Windows Live.COM)站在互联网浪尖上窃喜...
- ajax获取session值_【JavaWeb】91:Cookie与Session
- python 协程爬虫_Python爬虫进阶教程(二):线程、协程
- 安装Spark集群(在CentOS上)
- 两个DIV高度自适应方法(左右两个DIV高度一样)
- 矩阵分析与应用(5)
- Deeper引领WEB3.0世界:去中心化、 安全性和超高速率的统一
- 2012,当我们谈论移动互联网创业时,我们在谈论些什么?
- 谷歌浏览器部分iframe页面无法打开,跨域问题
- 网络负能量为何发展如此迅速?
- 图解弗洛伊德算法(每一对顶点之间的最短路径问题)
- linux 文件名带日期,在linux中追加日期到文件名
- mysql连接数尖刺激增_mysql最大连接数max_connections
- 2015年SaaS细分领域部分代表公司盘点 融资额近40亿
- 图神经网络时间序列预测,神经网络预测未来数据
- spm12安装与使用
- 创立了维基百科的人,竟然要颠覆维基百科?| 独家
热门文章
- oracle的update加并发,关于update操作并发问题
- linux racoon代码,源代码安装IPsec-Tools-0.7.2
- dotween unity 延时_使用DoTween在Unity中制作队列(Sequence)动画
- 下面哪一个不是python语言的合法命名_下面哪一个不是Python语言的合法命名
- 计算机图形学在线作业,18春北交《计算机图形学》在线作业一-2
- linux eof打印列表,Linux:结合cat和EOF输出到文本文件
- 在计算机上的英语作文,我和电脑的英语作文
- python-gui-pyqt5的使用方法-7--partial 传递参数的方法:
- mac input 不支持xls_如何将PDF转换成xls格式的表格
- 注意!思科Aironet 1830和1850系列存在硬编码密码,请尽快修复!