readme

README（注释和说明文档）

---

1. 为什么要有README文档**

简评：因为 README，6 个月后的你仍然知道当初写了什么；因为 README，其他人看一眼就能知道是否需要；因为 README，让你的代码更有质量；因为 README，你成了个作家。

README 是一种说明文件，通常随着一个软件而发布，里面记载有软件的描述或注意事项。这种档案通常是一个纯文字文件，被命名README.TXT、README.1ST或http://READ.ME等等；但也有RTF或DOC格式的读我档案。

2. README文档内容结构

• [功能描述]：主要描述一下这个项目的主要功能列表。
• [开发环境]：罗列使用本工程项目所需要安装的开发环境及配置，以及所需软件的版本说明和对应的下载链接。
• [项目结构简介]：简单介绍项目模块结构目录树，对用户可以修改的文件做重点说明。
• [测试DEMO]：此处可以简单介绍一下DEMO程序的思路，具体实现代码放在example文件夹中。
• [作者列表]：对于多人合作的项目，可以在这里简单介绍并感谢所有参与开发的研发人员。
• [更新链接]：提供后续更新的代码链接。
• [历史版本]：对历史版本更改 记录做个简单的罗列，让用户直观的了解到哪些版本解决了哪些问题。
• [联系方式]：可以提供微信、邮箱等联系方式，其他人对这个工程不明白的地方可以通过该联系方式与你联系

3. 好的README文档

3.1 建议命名方式——大写英文字母
它的档名通常是以大写英文来命名的，因为大写英文字母比小写有着较小的ASCII码；亦因此在一些以ASCII排序档案的环境里，它能被保证被列在档案列表的第一位。这种档案的特殊命名使任何人能第一时间发现并阅读这个档案，即使他们本身并没有关于 README 的相关知识。
3.2 README 应该要简洁而清晰

• 告诉他们这是什么（包括背景介绍）
• 向他们展示实际使用的样子
• 传授使用方法
• 告知其他可能相关的细节

举个栗子：

DEMO
===========================

###########环境依赖
node v0.10.28+
reids ~

###########部署步骤
1. 添加系统环境变量
    export $PORTAL_VERSION="production" // production, test, dev


2. npm install  //安装node运行环境

3. gulp build   //前端编译

4. 启动两个配置(已forever为例)
    eg: forever start app-service.js
        forever start logger-service.js


###########目录结构描述
├── Readme.md                   // help
├── app                         // 应用
├── config                      // 配置
│   ├── default.json
│   ├── dev.json                // 开发环境
│   ├── experiment.json         // 实验
│   ├── index.js                // 配置控制
│   ├── local.json              // 本地
│   ├── production.json         // 生产环境
│   └── test.json               // 测试环境
├── data
├── doc                         // 文档
├── environment
├── gulpfile.js
├── locales
├── logger-service.js           // 启动日志配置
├── node_modules
├── package.json
├── app-service.js              // 启动应用配置
├── static                      // web静态资源加载
│   └── initjson
│       └── config.js       // 提供给前端的配置
├── test
├── test-service.js
└── tools



###########V1.0.0 版本内容更新
1. 新功能   aaaaaaaaa
2. 新功能   bbbbbbbbb
3. 新功能   ccccccccc
4. 新功能   ddddddddd

其他栗子：Apache HTTP Server和GNU的README文档都很简洁