前言
我們在工作中很多時候都要做技術選型，去找尋既能滿足自己需求又靠譜的第三方庫；在前端開源生態季度繁盛的現狀下，只要不是太小衆的需求，我們很容易就能找到一堆相關的開源庫，那我們具體要怎麼做決策呢？我的做法是，先閱讀開源庫的說明文檔讓自己有一個感性的認識，然後挑選出其中的兩三個庫來進行更深入更全面的瞭解。如此說來，這說明文檔是不是就很像我們求職時的簡歷呢？“簡歷”關都過不了，何談“offer”啊！
本文將介紹一個庫（即不侷限於前端領域）所要具備的說明文檔，主要包括 README.md、CHANGELOG.md、LICENSE，這些說明文檔均需放置於項目的根目錄。
README.md
當我們進入 GitHub 中的某一個開源代碼倉庫頁面，除了項目信息、代碼目錄結構外，最先映入眼簾的就是 README.md 了，可見，其重要性不亞於 index.html 之於一個網站。
README.md 需要滿足以下這些要求：
- 準確（包括字母大小寫）命名爲
README.md - 符合 markdown 語法
- 每個章節都應有標題
- 中、英文連接處應有空格分隔
- 使用 markdown 語法包裹代碼片段，並注意標註代碼段的語言種類，如：
console.log('code in javascript');
必須包含的內容
一份優秀的 README.md 需要包含以下內容：
- 名稱：必須與庫的名稱保持一致。
- 簡介：以 markdown 語法
>開頭；儘量保持簡潔且字數應少於120；與 GitHub 倉庫（如果有的話）和 npm 包（同樣是如果有的話）的描述保持一致。 - 庫的安裝方法：如何安裝本庫，在前端領域下通常指如何安裝 npm 包或用
<script>加載 CDN 資源。 - 庫的使用方法：如何使用本庫，可列出最簡單的用法，讓用戶能夠以最快的速度把庫跑起來，這能夠高效地建立起用戶的信任。
- 開源許可協議：本庫的版權聲明，下文將詳細介紹。
- API：包括庫提供的方法、參數、事件等信息。
可選內容
除了以上必須包含的內容外， README.md 中還有一些對用戶友好的內容項，這些內容項往往會爲你的庫增色不少，所以如果可以的話，也請爲你的庫 README.md 加上：
- 目錄：帶錨點跳轉的鏈接，可使用工具自動根據 README.md 的各級標題來生成，詳情請參考 github-markdown-toc 。
- LOGO：一個好的 LOGO 會成爲你的庫的視覺識別標識，使你的庫更容易被用戶接受和記住。
- 徽章：徽章是由 shileds.io 提供的圖片，圖片上還可以按需附上超鏈接；徽章通常用於突出描述本項目在外部第三方平臺的狀態和數據，如項目的持續集成狀態（如果本庫配置有單元測試的話那一般還會包括代碼測試覆蓋率）、項目在某平臺（前端領域通常指的是 npm）的下載量、項目最新發布的版本號、開源協議等。
- 瀏覽器兼容性：如果本庫是在瀏覽器環境下運行的，那麼聲明本庫的瀏覽器兼容性可以幫助用戶快速完成技術選型。
- 安全風險：用於羅列本庫當前已被發現且未解決的安全漏洞及其風險級別，如有繞過的方法也請附上，這同樣可以幫助用戶快速做技術選型。
CHANGELOG.md
CHANGELOG.md 記錄了本庫每個正式發佈的版本，以及該版本所包含的內容。對於 GitHub 開源庫來說， CHANGELOG.md 中的內容應該與 GitHub 中的 releases 保持一致。
CHANGELOG.md 具體包含以下內容：
- 版本號
- 新特性(new features)
- 優化(optimization)
- Bug 修復(bug fixes)
- breaking changes
- 文檔(docs)
如果你覺得維護 CHANGELOG.md 比較困難，那麼其實也有工具可以從庫每次的 commit message 中分析生成 CHANGELOG.md ，但這對 commit message 的規範性有一定要求，本系列後續的文章裏會有詳細的介紹。
LICENSE
LICENSE 是本庫的版權聲明，聲明用戶可以在什麼範圍內使用、二次開發、商用本庫，具有法律效力，一般可以直接聲明使用現成的協議，如 GPL / BSD / MIT/ Mozilla / Apache / LGPL 等，本文不打算介紹如何選擇合適的協議，可參考《如何選擇開源許可證？》。
LICENSE 對於商業項目的技術選型有這一票否定的地位，因爲某些開源協議具有傳染性，若你的項目使用了這樣的開源庫，則你的項目也必須開源，這對於商業項目來說幾乎是不可接受的。
主流前端框架 React ，就曾因 LICENSE 問題，引發社區強烈不滿，並遭到不少大型公司棄用，最終迫於壓力下才改用最寬鬆的 MIT 協議，這才平息了風波。
多語言
請正確評估你所開發的庫的用戶羣體，如果庫的用戶羣體中包含他國人員，請爲他們準備好合適語言的說明文檔。而對於一個把源碼託管在公共代碼倉庫的開源項目來說，我建議至少準備中英文兩套說明文檔，這將大大擴展開源庫的用戶羣，畢竟既然辛辛苦苦做出來個開源庫，總還是想多收穫點 Star 和 Fork 的嘛嘿嘿~~
一般我們將默認一個說明文檔是使用英語的，而把使用其它語言的說明文檔的文件名上加上 IETF 語言代碼，如簡體中文的 IETF 語言代碼是zh-CN，因此 README.md 的中文文檔命名是README.zh-CN.md， CHANGELOG.md 的中文文檔命名是CHANGELOG.zh-CN.md，而 LICENSE 則只需要一份英文版的就足夠了。
實例項目代碼介紹
我會以我最近寫的兩個開源庫：javascript-library-boilerplate 和 vue-directive-window 來作爲實例項目代碼來輔助介紹。
javascript-library-boilerplate
javascript-library-boilerplate 是一個現代前端生態下快速構建 javascript 庫的腳手架（或稱種子項目，或稱示例代碼，看你理解了），本庫支持 GitHub 的 repository templates 功能，你可以直接在項目首頁點擊 Use this template 來直接套用本腳手架的代碼來創建你自己的 javascript 庫。
vue-directive-window
vue-directive-window 是一個可以快速讓模態框(modal)支持類窗口操作的增強庫；類窗口操作主要包括三大類：拖拽移動、拖拽調整窗口尺寸、窗口最大化； vue-directive-window 支持以 Vue 自定義指令或是一般 js 類的方式來調用。
vue-directive-window 相對於 javascript-library-boilerplate 來說，更貼近 Vue 生態圈，如果你最近想爲 Vue 生態圈添磚加瓦，不妨參考一下本項目。~~~~
系列文章目錄（同步更新）
想要閱讀更多我的技術文章？請到我的 GitHub 博客 Array-Huang/blog 來，如果對您有幫助的話請 Star&Watch 走一波哈(〃ω)