如何為專案編寫良好 README

語言: CN / TW / HK

README,它是別人對專案瞭解、印象的第一來源;尤其是針對開源專案,相當之重要:好比顏值之於一個人,主頁之於一個公司;但很多專案並未重視這一點;各種倉庫,浩如煙海,沒有簡潔、明晰的介紹,教人如何耐心去看?本篇文章的存在,即是為了改善這種情況。它將指導您如何寫出一篇友好、易讀的 README ,同時提供一鍵生成專業 README(模版)的工具,從而為廣大開發者,解決如何書寫良好 README 之煩憂;同時為諸多閱讀者,緩解沒有清晰 README 一窺專案主旨的苦惱。

一鍵生成 README.md

先前在瞭解 npx 相關功能時候,有特地在 Github Gist 上做了一個工具: Generate a good README ,如果您的電腦已經安裝 Node(version >= 5.2.0),那麼即可通過一條命令,快速生成一個良好 README,只需對其中具體內容做下修改即可。

# 預設英文 README  
npx https://gist.github.com/nicejade/406f154e882a836de1b2e12d02b84aab  
  
# 生成中文 README  
npx https://gist.github.com/nicejade/406f154e882a836de1b2e12d02b84aab zh

頂部資訊

顯而易見, Logo標題簡短描述 ,對於專案是必要的;它應該位於 README 頂部,且居中顯示;除此之外,還可以新增 徽章 (Badge),對專案進行標記和說明,這些好看的小圖示,不僅簡潔美觀,而且清晰易讀,您可以在這裡連結更多資訊,這有助於更好向他人展示自己的專案;正在維護的 nicejade/markdown-online-editor 專案,就新增有以下徽章:

如果您習慣使用中文,但專案又是國際化的,那不妨考慮以英文來書寫 README,這似乎更有逼格(畢竟程式碼也是英文);但為人性化考量,也應該提供其他語言版本 README,可以在 徽章 之下,新增網頁跳轉連結。

目標與哲學

為您設計的專案,寫下初衷、理念和目標。對建立和維護專案背後的動機,作簡短的闡述,這應該可以解釋為什麼該專案存在。

先決條件

說明使用者在安裝和使用前,需要準備的一些先決條件,譬如:

您需要安裝或升級 Node.js (> = 8。* ,Npm 版本 >= 5.2.0Yarn 作為首選)。

安裝

npm i

在特定的生態系統中,可能存在一種通用的安裝方式,例如使用Yarn,NuGet或Homebrew。但是,請考慮是否有可能正在閱讀README的人是新手,並且需要更多指導。

用法

npm start

列舉如何使用示例,並儘可能顯示預期的輸出。內聯您可以演示的最小用法示例很有幫助,同時提供指向更復雜示例的 Wiki 連結(如果它們太長而無法合理地包含在自述檔案中)。

功能支援(可選)

您可以用列表的形式,展示專案現在已經支援的功能或特性,這有助於他人對專案存在的價值,做更深一步瞭解。

螢幕截圖(可選)

包括 logo / demo 截圖等。

支援(可選)

告訴人們他們可以去哪裡尋求幫助。它可以是 issue 跟蹤器,聊天室,電子郵件地址等的任意組合。

測試(可選)

npm test

用程式碼示例描述並展示如何執行測試。

路線圖(可選)

如果您對將來的發行版有任何想法,最好在 README 檔案中列出它們。

貢獻(可選)

歡迎提出請求。對於重大更改,請先開啟一個 issue,以討論您要更改的內容。請確保適當更新測試。

作者和致謝(可選)

向那些為該專案做出貢獻的人表示感謝。

執照

MIT

版權所有 (c) 2020-至今, 您的名字

專案狀態(可選)

如果您沒有足夠的精力或時間來完成專案,請在 README 檔案的頂部添加註釋,指出開發速度已減慢或完全停止。可能有人會選擇 fork 您的專案,或者,以維護者或所有者的身份自願加入,從而使您的專案繼續進行下去。您也可以明確要求維護者。