如何編寫開源項目的 README 文檔

運營一個開源項目就像在運營著一家 Startup，你期待更多人來使用你的項目，並給你的項目加 Star/提交 PR，但好的項目除了其自身真正契合了開發者的需求外，還需要一個好的 README。

有好的 README 文檔的項目不一定是一個好開源項目，但一個好開源項目一定有一個好的 README。

目前 README 文檔編寫並沒有規範，但一個友好的 README 是有其特徵的，我們來看看一個好的 README 的必備要素。

國際化問題

首先要注意的是國際化問題，如果你希望自己的項目能獲得更多人的使用，提供中英兩種 README 文檔是非常贊的。你可以在項目頭部註明它。如 Coding 的 WebIDE 項目：

項目名及簡介

好的項目名及簡介是好項目必不可少的。開源項目名不宜過長（除非你有特別的理由這麼做），如果你不知道如何給自己的項目起名，可以使用 隨機項目名產生器（適用於 Javascript 項目）；項目簡介可以是簡單的幾句話，但項目簡介要說明幾個你的開源項目用戶想迫切了解的問題，這包括：

• 這個開源項目是做什麼的？
• 這個項目是什麼語言編寫的？
• 項目維護、CI、依賴更新狀態（如果有）
• 項目可用版本及其他版本
• Demo 或官網地址（如果有）

如 Coding 的 WebIDE 項目：

此外你還可以給項目增加一些圖標以提高可讀性，推薦使用 Shields.io

項目 Logo 和使用截圖

你還可以將項目 Logo（如果有的話）放置在 REAME 頂部（這裡推薦一個在線製作 Logo 的網站 Canva ），項目截圖（Gif 動圖更佳）也可以幫助你的用戶更快速更直觀地了解你的開源項目。

功能

你可以註明這個項目的功能特點，亮點特色會大大提高訪客使用這個項目的概率。

如 Coding 的 WebIDE 項目

用法

這是 README 中最重要的部分，你需要說明這個項目如何使用，這包括：

• 如何下載這個項目：一般情況下 git clone 該項目地址即可，當然你也可以提供其他包管理下載安裝方式；
• 項目依賴：你需要說明編譯運行這個項目前需要哪些依賴；
• 安裝：你需要說明如何編譯安裝/運行這個項目；
• 部署：如果這個項目可以部署的話，請最好註明部署要注意的事項；
• Debug 方法：理想狀況下，你的用戶會順利編譯並運行這個項目，但你要確保用戶遇到了問題不會來打擾你（如提交 Issues），你還需要提供用戶可能會遇到的常見問題；

  

貢獻

對於一個開源項目來說，令其作者最開心的莫過於有人提交 Pull Request 了。加入一個 CONTRIBUTING 文檔將大大提高他人貢獻你的項目的概率。

你可以說明你的代碼規範，項目架構，如何測試和提交 Pull Request 的正確格式，以及其他有利於開發者進行貢獻的信息，這將會使你的項目變得更加的規整如一。你可以在項目根目錄新建一個 CONTRIBUTING 進行詳細的說明並在 README 中添加其文件錨鏈接。如 Google 的 Template：

版權

版權是非常重要的，如果沒有聲明版權，很多用戶特別是企業級用戶將受制於法律問題，無法使用你的項目。關於如何選擇開源項目許可證，推薦閱讀這篇文章：《如何選擇開源許可證？》

如 Coding 開源的 幫助文檔 版權：

鳴謝

你還可以感謝直接或間接為這個項目做出貢獻的人、項目。

如 ttyd 項目：

其他

我們推薦使用 Markdown 編寫你的 README，請最好注意排版問題以增加文檔可讀性，推薦閱讀 Coding 的 《文案排版規範》。

這就是一個好的 README 所需元素了，當然你還可以增加其他任何利於開發者的信息如 Roadmap 等等，這因項目而異。現在，去完善你的開源項目信息或開始做一個開源項目吧！

一些建議：選擇一個好的代碼託管平台/社區可以讓你的開源項目獲得更多曝光，你可以在 Coding 的 冒泡社區（可以理解為程序員的朋友圈）發布你的項目簡介，截圖和地址，與 30 萬中國開發者分享你的開源項目；另外我們推薦同時 push 項目到 Coding 和 GitHub（可參考 該回答 ），得益於 Coding 遍布全國的 CDN，國內用戶 clone 你的項目時的速度將大大提升（PS：Coding.net 的私有代碼倉庫也是完全免費的）。

Happy Coding ; )

（完）

你可能會感興趣的文章：

• 《Coding 如何使用 Coding 開發 Coding》
• 《使用 Feature Branch Workflow 讓開發更簡單》
• 《使用原理視角看 Git》

推薦閱讀：