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

如何編寫開源項目的 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 你的項目時的速度將大大提高。

Happy Coding ; )

（完）

你可能會感興趣的文章：

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