简洁的README是一段开发旅程的美好开始
开发 开始 简洁 旅程 一段 美好 README
2023-06-13 09:18:47 时间
看到简洁高质量的README,是一段开发旅程的美好开始。
本文旨在通过一些示例和注意事项,指导下如何写出让人心情愉快的README。
1、2是作者常用的【业务项目】和【开源组件】的README编写规范。
3 是一个check list用于衡量你编写的README是否简洁高质量。
1. 业务项目README规范
业务项目的README,更多的是面向业务项目的开发者,我们应该注重呈现项目的具体实现细节。
这时候,目的是为了让新接手的开发者,能够快速地了解项目结构,上手开发、验证、部署、上线的流程,进一步得,对于前端项目,可以整理页面和路径的映射表格,方便开发者快速熟悉项目和定位问题。
同时,如果常用系统比如监控、数据上报、错误日志系统也贴上相关入口,会更锦上添花。
## 项目介绍
- [必填] 产品介绍
- [选填] 项目 LOGO/截图/演示GIF
- [选填] 项目背景
## 技术架构
- [必填] 技术选型
- [选填] 服务间关系 / 服务内实体关系及位置
## 快速上手
- [必填] 环境依赖与安装 / 常规功能开发流程
## 项目结构
- [必填] 文件目录结构
## 开发流程
- [必填] 开发机制 分支管理 代码评审与合并 部署过程 测试流程 / 上线流程;
- [选填] 可以是外链, 链接之外的再额外补充;
## 其他指引链接
- [选填] 监控链接
- [选填] 错误日志链接
- [选填] 上报数据链接
## 页面路径
- [选填] 页面和代码路径的映射
2. 开源组件项目README规范
开源组件项目的README,更多是面对组件的使用者,重点是告诉组件的使用者,组件是干什么的(what),如何快速上手组件(how)。
项目介绍最好能有一句提炼的话,总结出组件最核心的功能。
Q&A,是对组件使用者友好最直接的体现。
如果希望其他人参与组件的共建,或者希望使用者参与项目交流,可以加上【如何加入】和【团队介绍】。
## 项目介绍
- [必填] 产品介绍
- [选填] 项目 LOGO/截图/演示GIF
- [选填] 项目背景
## 快速上手
- [必填] 环境依赖与安装 / 常规功能开发流程
- [选填] API文档或者API链接
## 常见问题
- [选填] 项目常见问题和官方解答
## 如何加入
- [选填] 如何参与开源项目的贡献
## 团队介绍
- [选填] 成员的角色分工,官方交流渠道
3. 最后的Check List
引用README的艺术这篇文章的check list,编写好的README,过一遍check list,进一步完善。
- 一句话解释模块的目的
- 必要的背景资料或链接
- 为潜在不熟悉的术语提供到信息来源的链接
- 简洁可运行的实例
- 安装说明
- 详细的API文档
- 对认知漏斗的执行
- 前面提到的注意事项和限制
- 不要依赖图片传递关键信息
- 许可证
参考文章
相关文章
- 使用python的Django库开发一个简单的数据可视化网站(一)- 基本环境安装及配置
- 《笨开发学习操作系统》4进程间通信
- J2ME开发平台的搭建「建议收藏」
- 区块链交易所开发功能
- 手把手教你用 SpringBoot 开发微信公众号后台
- 让远程成为本地,微服务后端开发的福音
- Android Binder原理从开始到放弃详解手机开发
- 深圳:linux定制开发精彩开始(深圳linux定制开发)
- 荣耀Linux:为开发者重新定义开发体验(honlinux)
- 如何利用虚拟化技术解决物联网开发难题?从了解 ACRN 开始
- Linux下游戏开发:实现梦想的地方(linux下游戏开发)
- 开发Linux系统下的iPhone开发(linuxiphone)
- 2014年最热门的国人开发开源软件TOP100
- 大型网站如何利用Redis开发高效稳定的应用(大型网站用redis吗)
- 如何建立一个XML的开发环境