如何寫一個通用的README規范

背景

我們平常在進行項目開發時，一般都會把代碼上傳至代碼托管平台上方便管理和維護。目前我廠使用的托管平台是SVN，國內外還有一些比較知名的代碼托管平台，比如github、Gitlab、BitBucket，碼雲和碼市等。

但我們在多人合作開發下，經常碰到的最頭疼的問題是，其他開發者在交接給我們一個項目時只是對項目目前現有的功能簡單的描述了下，我們在后續迭代功能時突然發現連最基本的項目如何運行都沒有給我們交代，當時心中一萬只那個什么馬奔騰而過，只能去查看package.json的scripts，自己意會了。

那么問題來了，我們在交接一個項目時，如何保證項目能快速完整地交付給基友，從此過上無憂無慮的生活呢？答案是我們只需要甩給他一份標准規范的README。

 

規范的README需要哪些內容

我們一起來探討下，一份規范完整的README規范都應該有哪些內容呢？

1. 項目描述

2. 如何運行

3. 業務介紹

4. 項目備注

每一項都有哪些作用？

• 項目描述

  需要說明我們的項目名，項目功能簡述，代碼倉庫地址，以及該項目的第一負責人。誰交接給我們的項目，誰就是該項目的第一負責人。

• 如何運行

  1. 開發環境配置。一般是我們需要的一些運行環境配置。
  2. 開發&發布 命令。我們怎么通過命令開啟本地開發，以及構建發布。
  3. 代理配置。如果我們的項目在本地開發時需要用到一些代理工具，例如fiddler或whistle等，我們需要列出代理的配置項。最好是直接導出一個代理配置的文件，放在項目下
  4. 發布。如果我們有用到一些發布平台，最好貼上項目的發布模塊和發布單，減少我們發布的時間成本。
  5. 錯誤告警及監控。相信我們平常都會對線上的項目部署錯誤告警和監控日志的服務，方便我們及時排查現網問題，這里我們可以加入項目的一些監控屬性ID
  6. 接口API。這里我們需要貼入項目中拉去的后台接口地址以及描述，還有我們的接口負責人，當后台服務異常，可以直接聯系到后台同學。
  7. 數據上報。我們在平常項目里都有加入一些數據上報，給產品同學統計業務數據用，這里我們最好闡述下都有哪些數據的上報。如果上報出問題，產品妹子找過來，我們不至於是一臉懵逼。

• 業務介紹

  對於前端來說，我們一個項目可能不止一個頁面，那么我們需要給出以下信息:

  1. 業務入口地址及渠道鏈接 即我們整個項目的入口頁面，或者比較重要的頁面地址。一般入口頁面，我們可能會在多個渠道進行投放，那么需要列出所有的渠道鏈接

• 1. 各頁面及描述 列出我們項目內的所有頁面信息，比如下面這樣：

     頁面目錄	頁面描述	頁面鏈接	參數描述
     index	首頁	https://xxx.com	無

• 項目備注 項目中需要告訴其他開發者一些關鍵信息，比如我們頁面打包構建，需要注意哪些問題等等，這些信息雖然不是必須的，但是可以幫助其他開發者降低開發的風險成本。