文档章节

如何编写开源项目的 README 文档

fengyexjtu
 fengyexjtu
发布于 2016/11/21 01:46
字数 1321
阅读 161
收藏 4

行业解决方案、产品招募中!想赚钱就来传!>>>

如何编写开源项目的 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 ; )

(完)

你可能会感兴趣的文章:

fengyexjtu

fengyexjtu

粉丝 5
博文 53
码字总数 20823
作品 0
西安
程序员
私信 提问
加载中
请先登录后再评论。
用vertx实现高吞吐量的站点计数器

工具:vertx,redis,mongodb,log4j 源代码地址:https://github.com/jianglibo/visitrank 先看架构图: 如果你不熟悉vertx,请先google一下。我这里将vertx当作一个容器,上面所有的圆圈要...

jianglibo
2014/04/03
4.1K
3
beego API开发以及自动化文档

beego API开发以及自动化文档 beego1.3版本已经在上个星期发布了,但是还是有很多人不了解如何来进行开发,也是在一步一步的测试中开发,期间QQ群里面很多人都问我如何开发,我的业余时间实在...

astaxie
2014/06/25
2.7W
22
5分钟 maven3 快速入门指南

前提条件 你首先需要了解如何在电脑上安装软件。如果你不知道如何做到这一点,请询问你办公室,学校里的人,或花钱找人来解释这个给你。 不建议给Maven的服务邮箱来发邮件寻求支持。 安装Mav...

fanl1982
2014/01/23
1.2W
7
代码生成器--Codgen

Codgen是一个基于数据库元数据模型,使用freemarker模板引擎来构建输出的代码生成器。freemarker的数据模型结构通常来说都是一个Map树状结构模型,codgen也不例外,它的数据模型这棵树的根节...

黄天政
2013/01/29
1.4W
2
研究虚拟机--Jikes RVM

Jikes研究虚拟机(Jikes Research Virtual Machine,简称Jikes RVM)是一种成熟的用于执行Java程序的虚拟机,其早期版本与当前版本分别在通用公共许可证(CPL)与Eclipse公共许可证(EPL)下开...

匿名
2013/02/13
1.1K
0

没有更多内容

加载失败,请刷新页面

加载更多

开源FPGA单板iCESugar

随着产业的发展,近年来FPGA越来越得到市场的重视,5G、矿机、人工智能、图像识别、risc-v、通信等众多领域均可见到FPGA的身影,目前比较知名的FPGA厂商有xilinx、altera、lattice等,其中x...

whoisliang
58分钟前
6
0
合并记录帮助文档

合并记录步骤用于将两个不同来源的数据合并,这两个来源的数据分别为旧数据和新数据;该步骤将旧数据和新数据按照指定的关键字匹配、比较、合并,并显示差异信息。接下来就详细介绍一下该步骤...

osc_slnrw1du
58分钟前
19
0
Spark之RDD转换算子(transformation)大全

前面已经给大家讲过RDD原理,今天就给大家说说RDD的转换算子有哪些,以便大家理解。 对于转换操作,RDD的所有转换都不会直接计算结果,仅记录作用于RDD上的操作,当遇到动作算子(Action)时...

osc_3nr2bq5w
59分钟前
11
0
自定义常量数据帮助文档

自定义常量数据步骤主要用于增加自定义字段和行集数据到流中,可增加多个字段并为每个字段赋予行集的值。步骤配置信息如图1所示。 图1 自定义常量数据步骤配置信息 下文详细解释各控件的含义...

osc_r9wwwi0j
今天
10
0
Linux安装配置ftp(Ceonts 7)

1、安装vsftpd yum -y install vsftpd (我这里已经安装好了,只要不报错即安装成功) 安装完成后可以在/etc/vsftpd目录下看到vsftpd.conf 文件,这是vsftp的配置文件。 2、 添加一个ftp用户...

osc_tko37abm
今天
0
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部