編寫規範的readme文件

爲什麼要寫這篇博客？

　　其實我是一個入坑已經半年的程序員，因爲不是計算機專業，只能自己摸索，所以我深知博客的重要性。每次我的學習筆記啊，項目的，面試題啊，有的，只要有時間，我肯定上傳上來，一方面自己可以隨時隨地的看，另一方面也可以方便大家。

　　瞭解一個項目，恐怕首先都是通過其Readme文件瞭解信息。如果你以爲Readme文件都是隨便寫寫的那你就錯了。github，oschina git gitcafe的代碼託管平臺上的項目的Readme.MD文件都是有其特有的語法的。稱之爲Markdown語法，今天要寫的是關於README文件在windows中如何寫，怎麼寫出來才符合要求，寫出來纔好看，這樣就不得不說一下MarkDown編譯器了。

　　也許很多大神說，Markdown這麼簡單的，還需要寫個博客炫耀？

　　其實你錯了，對於我們這些在windows上操作慣了的野路子，根本對除了word之外的編輯語言不感冒，也不習慣，但是每次項目都會需要README文件，記得我第一次寫的README文件是TXT格式，被老師嘲笑了，說README文件是.md格式，但是我自己比較笨，請教了一個哥們，終於知道了寫README的好方法，那就是使用mardkdown工具，我下載的是有道雲筆記（我還用的是windows操作系統），他不但有MARKDOWN，更重要的是，還有MarkDown使用指南，（大家不要誤會，我不是推銷這個軟件，對於還是小白的我，覺得遇到了神器，很激動）。既然有這個了，那麼我的問題就迎刃而解了。

　　這篇文說到這裏，這纔剛剛開始，下面主要介紹一下 MarkDown的主要用法，方便大家寫README文件。

爲什麼要寫README文件？

　　對於這個問題詳解，請看博客：http://www.cnblogs.com/wj-1314/p/7551184.html

　　這個問題很簡單，因爲README的編寫，過了很長時間後，你仍然知道你當初寫了什麼；因爲README的編寫，其他人看你的代碼不需要那麼費勁；因爲README的編寫，你代碼的質量就大大的提高；因爲README的編寫，你的語言水平就大大的提高了。

　　所以說README應該簡短，大家不要以爲寫這個很麻煩，這個東西能夠節省你和別人的很多時間。

完整的README包括什麼內容？

　　關於README的內容，這是我覺得是每個項目中都應該有的一個文件，目的是能簡要的描述該項目的信息，讓讀者快速瞭解這個項目。

一，它需要說以下幾個事項：

1，軟件定位，軟件的基本功能

2，運行代碼的方法：安裝環境，啓動命令等

3，簡要的使用說明

4，代碼目錄結構說明，更詳細點可以說明軟件的基本原理

5，常見問題說明

二，它包括了一下內容：

項目和所有子模塊和庫的名稱（對於新用戶，有時不同命名會導致混亂）

對所有項目，和所有子模塊和庫的描述

如何使用 5-line code（如果是一個庫）

版權和許可信息（或閱讀許可證）

抓取文檔指令

安裝、配置和運行程序的指導

抓取最新代碼和構建它們的說明（或快速概述和「閱讀 Install」）

作者列表或「Read AUTHORS」

提交bug，功能要求，提交補丁，加入郵件列表，得到通知，或加入用戶或開發開發區羣的介紹

其他聯繫信息（電子郵件地址，網站，公司名稱，地址等）

一個簡短的歷史記錄（更改，替換或者其他）

法律聲明

3，一個簡單的範本（當然，我們前期寫的話，不必要那麼麻煩，就寫幾個簡單的必要的東西，比如法律聲明啊，聯繫記錄啊等等，就不必要寫）

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

###########環境依賴
node v0.10.28+
redIs ~

###########部署步驟
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