简洁的README是一段开发旅程的美好开始

1,027 阅读4分钟

一起养成写作习惯!这是我参与「掘金日新计划 · 4 月更文挑战」的第1天,点击查看活动详情

看到简洁高质量的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文档
  • 认知漏斗的执行
  • 前面提到的注意事项和限制
  • 不要依赖图片传递关键信息
  • 许可证

参考文章

README的艺术

往期好文

“告别烂代码”

2022代码规范最佳实践(附web和小程序最优配置示例)

【前端探索】告别烂代码!用责任链模式封装网络请求

【前端探索】告别烂代码第二期!用策略模式封装分享组件

代码人生

【三年前端开发的思考】如何有效地阅读需求?

前端踩坑必看指南

【前端探索】图片加载优化的最佳实践

【前端探索】移动端H5生成截图海报的探索

【前端探索】H5获取用户定位?看这一篇就够了

【前端探索】微信小程序跳转的探索——开放标签为什么存在?

【前端探索】vConsole花式用法