新手如何写一个项目的README.md

想写好一个README文件首先需要熟悉MarkDown语法，再次就不过多讲解了。

主要分为几个大的结构就像写简历一样123罗列出来即可;

1.项目概况

2.技术栈

3.项目结构

4.开发环境及依赖

5.友情提示

6.代码规范

7.项目规范

上例子

# 贝程教育-学员笔记助手

> 学员笔记助手前端项目说明文档，本文档旨在让参与项目人员了解项目结构, 项目依赖, 业务模块, 组件说明, git flow ...

## 技术栈

`vue2` `vuex` `vue-router` `vue-form` `node` `koa` `koa-router` `webpack` `scss`

## 项目结构

```

.

├── build // 构建脚本 webpack, devServer...

├── config // 配置 env, port, host, assetsPath...

├── node_modules // 依赖的第三方包

├── src // 源代码

│  └── client

│      ├── components // 前端通用组件

│      ├── containers // 路由匹配的各页面组件

│      ├── helpers // 功能函数

│      ├── images // 图片资源、

│      ├── routes // 路由配置

│      ├── service // 接口请求函数

│      ├── styles // 样式

│      ├── vuex // 全局 stote. 含有各模块的 action, mutation, getter, state...

│      └── main.js 项目入口文件

├── dist // 源代码编译后的生成线上环境代码

├── .babelrc // babel 配置

├── .editorconfig // 编辑器 code format 配置

├── .eslintrc.js // eslint 配置

├── .gitignore // 不纳入 git 版本控制的 /文件夹?/ 列表

├── package.json // 项目信息文件

└── README.md // 说明

.

```

## 开发环境依赖

- [node](https://nodejs.org/en/)

- [yarn](https://yarnpkg.com/zh-Hans/)

- [eslint](http://eslint.org/)

## 推荐工具

- [VS Code](https://code.visualstudio.com/) 写代码利器

- [SourceTree](https://www.sourcetreeapp.com/) 图形化 git

## 编辑器插件 (`无论使用什么IDE，下面列表中 * 开头的插件必装, 以下插件皆为 VS Code 中插件`)

- *ESLint

- *EditorConfig

- Vetur

- vue

- Babel

- Path Intellisense

## 让 VS Code 的 ESLint 插件支持 .vue 文件

> 打开 VS Code

> 打开用户设置 windows: 文件 > 首选项 > 设置

> 打开用户设置 mac: Code > 首选项 > 设置

> 在 user setting.json 添加下面的代码

```

"eslint.validate": [

    "javascript",

    "javascriptreact",

    "html",

    "vue"

]

```

## 代码规范 `(重要)`

> `!!!本项目遵从` [airbnb](https://github.com/airbnb/javascript) `js 规范， 并将检测集成进 webpack , 所以不符合规范代码无法编译成功。`

> 可以使用编辑器插件自动检测代码规范, 如上方 VS Code 的 ESLint 插件, 其他编辑器自行 google

## 通用组件

- [BackBg](./doc/components/backBg.md)

- [Header](./doc/components/header.md)

- [SvgIcon](./doc/components/svgIcon.md)

- [Loading](./doc/components/loading.md)

## SVG 图标 页面

执行以下命令会使用默认浏览器打开 svg 图标页面， 项目中使用的图标尽收于此，单击图标复制代码，组件中引入 SvgIcon 直接粘贴复制的图标代码便可使用

```bash

$ npm run openSvg

```

## run & build

```bash

# cd 到项目目录

$ cd workspace/wechat-restaurant

# 安装依赖

$ npm install

# 启动开发环境

$ npm run start

```

## git flow

### 分支

- master        // 主干

- dev          // 开发主干

- release      // 测试分支

- feature      // 功能分支

- fixbug        // bug 修复分支

### 工作流

> 项目人员开发时由 dev 分支创建新的 feature 分支，分支命名规则为对应的任务名字

> 开发完成后， 向 leader 发起 pull request, code review 完毕合并入 dev 分支

> 提测时从 dev 分支拉出 release, bug 由 release 分支拉出 fixbug 修复, 修复后发起 pull request, code review 后合并入 release 与 dev

以上请复制到README.md中预览效果，不喜勿喷！