videojs中文文档详解_你的项目需要一个高质量README文档!
来源丨续渊
juejin.im/post/5cdd09556fb9a0323968b033
无论在公司内部,还是在开源社区,我们在接触一个新项目的时候,基本上都会先去看README。一份好的README可以使你快速了解甚至上手这个项目,然而一份糟糕的README可能会让你崩溃。
README就像是一本供开发者阅读的程序简介书。为了写好这本书,给别人或者自己提高效率,我们需要学习一些技巧来编写高可读性的README.
README(顾名思义——"读我")是开始一个新项目的时候首先需要阅读的文件。它是关于项目有用信息的集合,同样也是一本手册。
比如:我这个位于 Github上关于 Spring Boot的开源项目,其README就是这个:
对于使用你项目的人而言,一份好的REAME可以让其他人迅速了解我们的代码包含的内容、重点、使用方法、技术栈、疑难杂症等。这毫无疑问可以大大减少沟通成本。如果你不想不厌其烦地回答新人的各种问题,那就写一份完整且高可读性的README吧。
而对于我们自身而言,README不仅可以让你在久别重逢该项目后找到往日的熟悉感,它也可以帮助我们总结和规划。我们可以将解决问题的灵感来源记录(如stackoverflow链接),也可以添上完成的功能和即将要实现的特性和优化。从这个角度来说,它像是一本关于项目的日记或者蓝图。
如果是开源项目,我建议使用英语。毕竟咱们要有一颗international的心。如果是公司内部项目,还是中文“可读性"更强。当然,这个不强求
首先至少应该包括的内容有:
标题(Title)
介绍(Introduction)
技术栈(Technologies)
启动(Launch or Setup)
如果考虑得更完善一些还包括:
目录(Table of contents)
功能特性(Features)
代码示例(Code Examples)
项目状态(Status)
来源(Sources)
外部链接(Links)
联系(Contact)
其它信息
...
当然关于内容规范问题仁者见仁智者见智,只要能够达到README应该有的效果,就是好的实践。
标题(title)
一个标题应该很清晰地表达这是一个什么项目。通常来说,它会是项目名称。
介绍(introduction)
介绍应该短小精悍,2、3句话就可以讲明白这个项目的目的以及解决的问题。
技术栈(Technologies)
这是程序员最关心的部分之一。它们是这个项目的地基,有了完整且正确的它们才能构建出整个项目,而不是一启动就无数报错。所以我们理应把项目的语言、依赖和对应的版本写下来。比如:
Java 8
Spring Boot 2.x
easyexcel 1.1.0
启动(Launch or Setup)
如何运行也是开发者十分关心的部分。我们不能仅仅只写下一行启动命令,比如 npm run start
,通常来说我们还需要告诉使用者如何安装依赖、如何修改配置甚至初始化数据库。你写得越详细,别人就越少吐槽。
目录(Table of contents)
在篇幅较长、内容较多的情况下,目录提供了一个各部分内容的快捷入口,而不是无止尽地滑滚轮。我们可以用 markdown
提供的便捷语法,创建一个简单的目录。
功能特性(Features)
通过阅读这部分,人们将迅速了解该项目所支持的功能和特性。另外我们也应当将TODO List写上去,以供自己规划项目和他人了解它的未来发展方向。
代码示例(Code Examples)
这对一些工具或者库依赖项目来说是十分重要的。因为通常来说人们更愿意直接复制粘贴来测试他们需要的效果。
项目状态(Status)
项目处于开发阶段还是已经完成,是已经停止维护还是迁移到了新的项目?这值得告诉读者。
来源(Sources)
我们在开发某项功能,或者解决某个bug的过程中,有的时候会查阅一些文档、教程或者从技术论坛寻找现成的解决方案(比如stackoverflow、掘金等)。将其中你认为对自己或他人有价值的一部分记录在案,写下它们的描述和链接。我认为在未来某个时间点,它可能会帮助到你或者别人。
外部链接(Links)
对于公司内部项目而言,可能会有项目管理平台地址(如tapd)、接口文档地址;对于开源项目也可能有对应的完整文档、教程、博客等。
联系(Contact)
主要是记录作者本人或者开发团队的联系方式。
上述都只是个人看法和建议,只要适合自己的项目,可读性高,达到减少沟通成本的目的就是好的README。
后 记
若有错误或者不当之处,可在本公众号内反馈,一起学习交流!
更多热文在此:
● Spring Boot 系列实战文章合集(源码已开源)
● 程序员写简历时必须注意的技术词汇拼写
● 基于Spring Security OAuth2的SSO单点登录+JWT权限控制实战
● 从一份配置清单详解Nginx服务器配置
● 如何在Windows下像Mac一样优雅的开发
● Docker容器可视化监控中心搭建
● 利用ELK搭建Docker容器化应用日志中心
● RPC框架实践之:Google gRPC
● 一文详解 Linux系统常用监控工具
更多 务实、能看懂、可复现的 技术文章、资源尽在公众号 CodeSheep,欢迎扫码订阅,第一时间获取更新 ⬇️⬇️⬇️
videojs中文文档详解_你的项目需要一个高质量README文档!相关推荐
- 专业的LaTeX: 在Linux下编写高质量的文档
专业的LaTeX: 在Linux下编写高质量的文档 Linux下的OpenOffice.KWord等字处理软件虽然在功能上与Microsoft Word类似,但目前在易用性和可用性方面仍然存在许多不足 ...
- LaTex在Linux下编写高质量的文档
肖文鹏 2003 年 10 月 01 日发布 目录 一.简介 二.TeX系统 三.LaTeX排版流程 四.LaTeX系统安装 五.LaTeX文档处理 六.小结 一.简介 计算机技术的不断进步推动了各行 ...
- texlive - 专业的LaTeX: 在Linux下编写高质量的文档
dnf install texlive* dnf install texworks dnf install latex* http://www.ibm.com/developerworks/cn/li ...
- LaTeX入门解析篇: 在Linux下编写高质量的文档
★内容概要 一.简介 二.TeX系统 三.LaTeX排版流程 四.LaTeX系统安装 五.LaTeX文档处理 六.小结 1.简介 计算机技术的不断进步推动了各行各业的飞速发展,使许多行业出现了革命性的 ...
- java 生成一个空文件系统_如何使用java创建一个空白的PPT文档?
在Java编程中,如何创建一个空的PPT文档? 注意:需要访问网址: , 下载一个Apache POI软件包.这里下载最新版本:poi-bin-3.17-20170915.tar.gz解压并全部导入 ...
- java 内存分布_java的各类型数据在内存中分配情况详解_
1. 有这样一种说法,如今争锋于IT战场的两大势力,MS一族偏重于底层实现,Java一族偏重于系统架构.说法根据无从考证,但从两大势力各自的社区力量和图书市场已有佳作不难看出,此说法不虚,但掌握Jav ...
- Javadoc (Java API 文档生成器)详解 [Javadoc 概述][Javadoc 标签][Javadoc 命令][Javadoc 生成 API 文档]
您的"关注"和"点赞",是认可,是支持,是动力. 如意见相佐,可留言. 本人必将竭尽全力试图做到准确和全面,终其一生进行修改补充更新. 文章目录 1 Javad ...
- tracepro应用实例详解_建筑安装工程造价,高清PPT图文详解,小白也能学会的简单步骤...
建筑安装工程造价,高清PPT图文详解,小白也能学会的简单流程 工程造价的直意就是工程的建造价格,是指进行某项工程建设所花费的全部费用.工程造价在工程中是很关键的存在,是工程能够取得的关键:对工程建设的 ...
- word怎么将文档分成三节_分节排版,就是将Word 2010的文档分节,使文档在不同的节中具有不同的______。(2.0分)_学小易找答案...
[单选题]I was walking along the Qiantang River when I noticed the beautiful sun setting. I snapped a fe ...
最新文章
- PAT (Advanced Level) 1132~1135:1132 模拟 1133模拟(易超时!) 1134图 1135红黑树
- 【IOS 开发】Objective - C 入门 之 数据类型详解
- centos安装mysql 简书_在centos上安装mysql
- 前端学习(3158):react-hello-react之一个简单的helloworld
- 算法眼中的世界是什么样子?他们用一些彩色方块画了出来
- Disable Auto Detect Keyboard Layout in Win10
- mycat 分表子查询_mysql分库分表之mycat中间件解决方案
- 2019eclipse 中文汉化包 安装教程
- MATLAB与Hspice联合仿真
- Material Design(二)--色彩样式
- 我的个人网站,终于上线了!
- 1467 B. Hills And Valleys
- 小型机和PC服务器差异分析
- c++primer plus 第六版 第六章重点内容总结 以及编程题答案
- python容器类型——字典{dict}
- 微信小程序上实现 table 表格
- FLASK RESTFUL TOKEN用户验证笔记
- 多发性硬化功能磁共振成像
- 云计算与云存储,具体是什么关系?
- 供应链计划的五个步骤,你知道吗?