如何编写开源项目的 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([链接])提供给企业用户全套 DevOps 研发管理工具,包括项目管理,代码托管,制品管理等功能,...

CODING 是腾讯云旗下一站式 DevOps 研发管理平台,向广大开发者及企业研发团队提供代码托管、项目协同、...

3.3k 声望
4k 粉丝
0 条评论
推荐阅读
线上直播 | 未来金融研究所——以应用为中心,重塑金融研发效率

CODING阅读 580

来自开发者的点赞,SOFAStack 入选 2022 中国技术品牌影响力企业榜
作为中国领先的新一代开发者社区,SegmentFault 思否依托数百万开发者用户数据分析,各科技企业在国内技术领域的行为及影响力指标,最终评选出 30 家上榜企业。

SOFAStack阅读 876

封面图
新一代 CI 即将到来!
本文转载 CodeSheep。作者受邀参加 Techo Day 腾讯技术开放日线上活动,收获颇丰,有感而发。前言上期 Techo Day 腾讯技术开放日活动讲的是「轻量级工具」,这一期主要讲的是「云原生」。在所有课题里,个人比较...

CODING阅读 874

封面图
LiteFlow v2.9.4发布!一款能让你系统支持热更新,编排,脚本编写逻辑的国产规则引擎框架
我们每次的发布的issue有很大一部分依托于我们的使用者社区,社区人越来越多。我看到了使用者在使用过程中遇到的问题,也收集了很多使用过程中很有意思的建议。这些也正是我们每一次迭代的方向。谢谢那么多的小伙...

铂赛东阅读 743

封面图
Excelize 开源基础库 2.7.0 发布, 2023 年首个更新
Excelize 是 Go 语言编写的用于操作 Office Excel 文档基础库,基于 ECMA-376,ISO/IEC 29500 国际标准。可以使用它来读取、写入由 Microsoft Excel™ 2007 及以上版本创建的电子表格文档。支持 XLAM / XLSM...

xuri阅读 613

“开源是一个自我实现的预言”,Shifu创始人陈永立说道
在 中国开源年会COScon2022 北京线下分会场中,Shifu 开源项目不仅是北京分会场的组织者,Shifu 的创始人 陈永立 也受邀在圆桌论坛环节与另几位在开源领域深耕多年的嘉宾大咖聊聊他们对于开源的看法。

物联网Shifu阅读 425

服务全球开发者!灵雀云与Ubuntu推出一体化云原生解决方案
近日,国内企业级云原生解决方案的领军企业灵雀云,与操作系统软件Ubuntu的原厂企业Canonical(以下简称Ubuntu)共同宣布达成战略合作。双方将提供操作系统软件Ubuntu与云原生开放平台ACP的深度融合一体化解决方...

灵雀云阅读 375

封面图

CODING 是腾讯云旗下一站式 DevOps 研发管理平台,向广大开发者及企业研发团队提供代码托管、项目协同、...

3.3k 声望
4k 粉丝
宣传栏