文档章节

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

fengyexjtu
 fengyexjtu
发布于 2016/11/21 01:46
字数 1321
阅读 15
收藏 0
点赞 0
评论 0

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

(完)

你可能会感兴趣的文章:

本文转载自:https://blog.coding.net/blog/how-to-make-readme

共有 人打赏支持
fengyexjtu

fengyexjtu

粉丝 5
博文 48
码字总数 20075
作品 0
西安
程序员
如何在开源世界打造自己的明星 Project?

本文来自作者 王爵nice 在 GitChat 上分享「如何进入开源世界并打造自己的明星 Project?」,「阅读原文」查看交流实录 「文末高能」 编辑 | 莫兰迪 我相信很多人多多少对开源软件都会有所了...

gitchat ⋅ 2017/11/27 ⋅ 0

开源项目的README文档应该这样编写

看过很多开源库,发现有些库的文档写的一团糟,有的甚至就是一个标题,让你自己下载之后运行,自己摸索,看的很头疼。而那些使用量大的库的文档写的很标准,很详细,看的很舒服。 README文档...

AWeiLoveAndroid ⋅ 03/06 ⋅ 0

把一个库开源,你该做些什么[转载]

把一个库开源,你该做些什么 译文作者: 咧威 原文地址: On Open Sourcing Libraries 简要概括:TL;DR (Too long; didn't read) 把一个库[1]开源非常简单,仅需几秒钟。你所需要做的仅仅是把...

超级小胖 ⋅ 2013/08/10 ⋅ 0

Kindle 上的开源阅读器--Koreader

我们希望在我们的阅读设备上能够享受这些自由: 数字内容不被局限于特定厂商的专有系统的自由。 用户可以获得阅读器软件运行细节,保障数字内容不被非法窥探的自由。 用户修改阅读器软件外观...

匿名 ⋅ 2013/03/31 ⋅ 0

如何参与一个GitHub开源项目

最近一年开源项目特别的热,很多技术大会或论坛都以开源项目作为主题进行探讨,可见这是一种趋势。而Github作为开源项目的著名托管地,可谓无人不知,越来越多的个人和公司纷纷加入到Github的...

DragonRiver2015 ⋅ 2015/03/18 ⋅ 0

C 的图形界面开发库 - LCUI

LCUI 是一种自由和开放源代码的图形界面开发库,主要使用 C 语言编写,支持使用 CSS 和 XML 描述界面布局和样式,可用于构建简单的桌面应用程序。需要特别注意的是,LCUI 采用的开源许可证是...

司徒永超 ⋅ 2012/05/03 ⋅ 27

如何做一个真正牛X 的开源项目

近年来,越来越多的开发者选择将自己的产品以开源形式发布,有时的结果是——你满怀诚意地开源,却无人问津。尽管你的产品做得相当好,但是仅把产品的源代码公布出来,这还不算开源,因为其他...

oschina ⋅ 2013/04/25 ⋅ 23

如何在 Github 打造你的爆款项目

目前为止我已经有五个流行项目(登上Github的Trending页),所以想分享我的一些经验和方法。 如果你开源过代码,就会知道让别人对你的感兴趣是多么困难。这很奇怪,不是吗? 我们花了至少数百...

oschina ⋅ 2016/07/19 ⋅ 13

从 Word 到 Docbook, 最后用 Pandoc, 让程序员爱上写文档

写文档一直是程序员非常讨厌的工作, 甚至和改需求一样令人厌烦. 在程序员眼里比写程序还难, 即便强制执行下来文档质量也很难让人满意. 相信大多数公司写文档都是用 Word, 笔者也是用了 Word...

震秦 ⋅ 2015/05/17 ⋅ 0

开源项目的最佳实践

来自GitHub的Phil Haack在Channel 9网站上举办了一次座谈会,专注于谈论开源项目的最佳实践。 本次会议的四位与会者都是开源项目的维护者,包括来自微软拉美区的听众布道经理(Audience Evan...

oschina ⋅ 2015/12/13 ⋅ 1

没有更多内容

加载失败,请刷新页面

加载更多

下一页

CENTOS7防火墙命令记录

安装Firewall命令: yum install firewalld firewalld-config Firewall开启常见端口命令: firewall-cmd --zone=public --add-port=80/tcp --permanent firewall-cmd --zone=public --add-po......

cavion ⋅ 48分钟前 ⋅ 0

【C++】【STL】利用chromo来测量程序运行时间与日志时间打印精确到微秒

直接上代码吧,没啥好说的。头疼。 #include <iostream>#include <string>#include <ctime>#include <sstream>#include <iomanip>#include <thread>#include <chrono>using ......

muqiusangyang ⋅ 51分钟前 ⋅ 0

Mac环境下svn的使用

在Windows环境中,我们一般使用TortoiseSVN来搭建svn环境。在Mac环境下,由于Mac自带了svn的服务器端和客户端功能,所以我们可以在不装任何第三方软件的前提下使用svn功能,不过还需做一下简...

故久呵呵 ⋅ 今天 ⋅ 0

破解公司回应苹果“USB限制模式”:已攻破

本周四,苹果发表声明称 iOS 中加入了一项名为“USB 限制模式”的功能,可以防止 iPhone 在连接其他设备的时候被破解,并且强调这一功能并不是针对 FBI 等执法部门,为的是保护用户数据安全。...

六库科技 ⋅ 今天 ⋅ 0

MyBtais整合Spring Boot整合,TypeHandler对枚举类(enum)处理

概要 问题描述 我想用枚举类来表示用户当前状态,枚举类由 code 和 msg 组成,但我只想把 code 保存到数据库,查询处理,能知道用户当前状态,这应该怎么做呢?在 Spring 整合MyBatis 的时候...

Wenyi_Feng ⋅ 今天 ⋅ 0

synchronized与Lock的区别

# <center>王梦龙的读书笔记第一篇</center> ## <center>-synchronized与Lock的区别</centre> ###一、从使用场景来说 + synchronized 是能够注释代码块、类、方法但是它的加锁是和解锁使用一......

我不想加班 ⋅ 今天 ⋅ 0

VConsole的使用

手机端控制台打印输出,方便bug的排查。 首先需要引入vconsole.min.js 文件,然后在文件中创造实例。就能直接使用了。 var vConsole = new VConsole(); vConsole的文件地址...

大美琴 ⋅ 今天 ⋅ 0

Java NIO之字符集

1 字符集和编解码的概念 首先,解释一下什么是字符集。顾名思义,就是字符的集合。它的初衷是把现实世界的符号映射为计算机可以理解的字节。比如我创造一个字符集,叫做sex字符集,就包含两个...

士别三日 ⋅ 今天 ⋅ 0

Spring Bean基础

1、Bean之间引用 <!--如果Bean配置在同一个XML文件中,使用local引用--><ref bean="someBean"/><!--如果Bean配置在不同的XML文件中,使用ref引用--><ref local="someBean"/> 其实两种......

霍淇滨 ⋅ 今天 ⋅ 0

05、基于Consul+Upsync+Nginx实现动态负载均衡

1、Consul环境搭建 下载consul_0.7.5_linux_amd64.zip到/usr/local/src目录 cd /usr/local/srcwget https://releases.hashicorp.com/consul/0.7.5/consul_0.7.5_linux_amd64.zip 解压consu......

北岩 ⋅ 今天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部