如何写一个高逼格 README
最近一个项目从程序员变成了一个高级文档哥,好吧,我还称不上高级,但是我发现写文档真不是一件容易的事情,要怎么写的让人看的舒服、巴适、爽的不行,看完就想给你个赞呢?我也总结了一下写文档的一些感想,也不能说是经验,毕竟小弟还年轻,哈哈。
编写一个项目的 README 就像是写一本书的序言一样,一个好的项目不应该仅仅只有一份高质量代码,同时更应该有一份高质量的文档。而对使用者来说,一份好的文档能够节省大量的时间。
国际化
要知道比如 GitHub 这样的代码托管平台,可是有着另一个名字,全世界最大的同性交友网站(技术基不说话),你的项目可能不止中国的程序猿在使用,一个好的项目,使用者来自世界各地,那么一份中英双语的文档至关重要。
毕竟对母语的文档有更加亲和的感觉,同时阅读起来会更加顺畅。
比如,Ant Design Pro 的文档:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f89bf94f7d20_w-571_h-137_f-png_s-6583.gif)
项目是干什么的
首先,要有一个项目名,不一定要霸气,但是一定要朗朗上口,不会读起来很拗口,而且别太长。
比如说,chalk、react、vue、commander 等等。如果自己实在不知道怎么起,搞个随机函数,试试自己的运气吧。
当然了,如果你有 LOGO 是最好的了,一张高清大图 LOGO 帅一脸,看起来就舒服有木有。
就比如说这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626fb0920c2315e_w-328_h-167_f-png_s-3171.gif)
或者这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8a1cdd0035f_w-219_h-238_f-png_s-17593.gif)
再接下来,一个好的项目简介,能够帮助使用者了解他能够使用这个工具干什么,能不能满足自己的需求。一般来说,我们希望从简介中,了解下面一些信息:
- 什么语言写的?Node、Python 还是其他什么
- 这个项目的用途是什么
- 最新版本信息
- 构建、测试结果等信息
- Demo 演示地址或者官网
就像这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8a44a7837b4_w-763_h-182_f-png_s-18214.gif)
对于我们技术 README 一定要各种徽章砸脸上,比如标配的 travis、coverage、npm 等等,给人一种安全感,如果你自己测试构建都没过,我用着也不放心。至于这些东西大家可以去这儿看看: shield.io
同时,我们要精要的总结项目的闪光点,有哪些特性是激动人心的,别人没有的,这是吸引用户的好方法。
比如这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8a65b54c92d_w-633_h-182_f-png_s-14873.gif)
安装及快速开始
这部分内容是是文档很重要的部分,通过这些步骤,能够让使用者快速的使用。
首先,你要告诉用户怎么去获取以及初始化项目,比如下面这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8a919986c90_w-700_h-285_f-png_s-16482.gif)
然后你需要给一个简单的例子,让使用者快速感受到使用它的好处:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8aaee7a668e_w-687_h-387_f-png_s-24840.gif)
当然了,在这个地方,最好最直观的方法就是放一张 gif 的图片,吸引用户的注意力,同时给用户展示使用结果,比如这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8cd4c256122_w-722_h-382_f-gif_s-672786.gif)
API
API 是一个项目的灵魂,这是暴露给用户最直接的地方,当使用者有疑问的时候,他会第一时间去找你的 API 文档。
对于一个 API 应该表述清楚的是:
- 作用
- 入参及每个参数是否必须,数据类型是什么等等
- 返回值
如果你的 API 不多,那么可以放在一个文件里,但是如果你的 API 非常多,那么建议你将 API 单独放到一个文件里,这个文件留一个链接就可以。
同时,如果你的 API 有相当多个版本,那么需要准备几份 API 文档,应对不同的需求。
就比如这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8b5b3ff3ab6_w-735_h-84_f-png_s-5465.gif)
版本变化
还有最好是能有一份 CHANGELOG 文档,对不同版本做了哪些修改,有什么特性等等,让用户知道每个版本干了什么。
就比如这样:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8b83e79197d_w-870_h-575_f-png_s-56228.gif)
FAQ
当然了,如果你不想回答一些非常重复的问题,我想你需要一份 FAQ 来记录一些常见问题。
贡献
我相信很多人跟我一样,能给一些知名仓库提交 PR 是一件比较自豪的事情。
所以如果能提供一个提交 PR 的方式或者是途径,能够吸引更多的人来贡献代码,同时将贡献者,展示出来,我想会有更多人愿意贡献出自己的力量。
比如在这样的列表中也是挺有意思的:
![](http://www.mk2048.com/web_upload/blog_imgs/6/https___user-gold-cdn-xitu-io_2018_3_29_1626f8bb46e1cc35_w-920_h-175_f-png_s-283355.gif)
版权
相信前不久 Facebook 的开源协议事件大家都知道,也是闹得沸沸扬扬,所以,对于开源协议等等的版权问题一定要慎重,如果你想做的不是一个玩具项目,那么关于这块一定要写清楚。
总结
最后,总结一下,对于一份好的 README 来说,这些也许够了,也许不够,但是,文档始终是因为使用者才存在的东西,所以使用者关注什么,什么才是我们文档的重点。
但是这些基础是我们应该都需要的:
- 名字
- 简介
- 功能
- 安装配置
- 快速教程
- API 文档
这些是使用者都会去关心的点,应该在编写之前好好斟酌。
这些只是我在做一些文档工作的时候,查看了挺多的文档,综合感想,写了这么多,但是实际情况可能会大有不同,所以具体是不是要这么写,大家见仁见智啦!
如何写一个高逼格 README相关推荐
- Markdown 工程师也不简单:如何写一个高逼格 README
最近一个项目从程序员变成了一个高级文档哥,好吧,我还称不上高级,但是我发现写文档真不是一件容易的事情,要怎么写的让人看的舒服.巴适.爽的不行,看完就想给你个赞呢?我也总结了一下写文档的一些感想,也不能 ...
- 打造一个高逼格的android开源项目——小白攻略
小引子 在平时的开发过程中,我们经常会查阅很多的资料,最常参考的是 github 的开源项目.通常在项目的主页面能看到项目的简介和基本使用,并且时不时能看到页面汇中有好多的彩色标签,看起来很酷,很专业 ...
- python发朋友圈_用 Python 发一个高逼格的朋友圈
原标题:用 Python 发一个高逼格的朋友圈 源 /痴海文 /痴海 分享一个非常骚气的发朋友圈姿势.效果如下. 利用今天教给大家的 python 脚本,把一张图重新分隔成 9 张.上传到朋友圈,最后 ...
- python朋友圈图片_用Python发一个高逼格的朋友圈
原标题:用Python发一个高逼格的朋友圈 今天要给大家介绍一个Python库:PIL(Python Image Library) 下面我们用一个实际的例子,看看50行python代码可以做什么神奇的 ...
- 用 Python 发一个高逼格的朋友圈
源 / 痴海 文 / 痴海 分享一个非常骚气的发朋友圈姿势.效果如下. 利用今天教给大家的 python 脚本,把一张图重新分隔成 9 张.上传到朋友圈,最后就会形成上面的效果.可能有些人在朋友圈有 ...
- 如何定义一个高逼格的原生JS插件
作为一个前端er,如果不会写一个小插件,都不好意思说自己是混前端界的.写还不能依赖jquery之类的工具库,否则装得不够高端.那么,如何才能装起来让自己看起来逼格更高呢?当然是利用js纯原生的写法啦. ...
- 如何用 javascript 做一个高逼格的进度条
可能你发现了本站顶部的进度条,它是如何实现的呢?下面一起来看. 页面进度条展示的是资源下载的进度,通常在页面上加上进度条,可以缓解用户的等待焦虑,也提升了网站的逼格. 前端进度条实现 在前端,实现网页 ...
- 用Python发一个高逼格的朋友圈【附代码】
如题,此文转自知乎: 公众号:[大数据前沿]编程,教程,大数据 作者:二胖 今天作者给大家介绍一个Python库: PIL(Python Image Library) 下面我们用一个实际的例子,看看 ...
- python发朋友圈_10分钟教你用Python发一个高逼格的朋友圈
程序猿声 你与千万程序猿在一起 01 前言 Hello~各位小伙伴们大家好.现在大家是越来越离不开手机,离不开微信了.每天打开手机的第一或者第二件事就是赶紧打开朋友圈看看有什么好玩的东西.偶尔忍不住了 ...
最新文章
- Serverless特点及应用
- jquery Syntax error, unrecognized expression:的解决方法
- linux系统性能测试之虚拟内存管理篇
- 面试体验:Facebook 篇(转)
- HTML meta 标签总结
- [C/C++] C++笔试常见问题
- jsp员工管理系统mysql_基于JSP的企业员工信息管理系统的设计(MySQL)
- python绘制emoji_使用Emoji表情拼成汉字
- 利用邮件合并批量制作带照片的准考证
- 生成自签名证书:生成证书和秘钥
- 不要急,没有一朵花,从一开始就是花,也不要嚣张,没有一朵花,
- ISTQB FL初级认证系列01:ISTQB FL初级认证考试说明
- xxtea 加密解密
- OpenCV学习:基础图像操作 (四):绘制几何图形
- mysql表的增删改select 和 where
- c语言编程 目录,C语言编程实例简介,目录书摘
- t6文件服务器怎么设置,t6文件服务器设置
- 图片加载—Glide为什么这么强?Glide源码分析(下)
- 摩拜共享单车技术含量
- JavaWeb项目打包成桌面程序,内嵌浏览器、tomcat、jre、mysql,实现一键安装
热门文章
- 指向 类成员函数 的 函数指针
- oracle变mysql,Oracle变换成为Mysql注意事项
- 完整且详细的单链表代码
- 计算机二级msoffice设计,2017计算机二级MSoffice攻关必做题
- SpringBoot2整合ElasticSearch(包含ElasticSearch入门+spring-boot-starter-data-elasticsearch)
- SQL的基本和常用语句
- Pose for Everything: Towards Category-Agnostic Pose Estimation 阅读笔记
- @Autowire和@Resource区别
- GBase 8a语法格式
- ChatGPT会对未来5年的NLP算法从业者带来怎样的冲击?