README 範本

每個區塊各自在回答什麼

每個區塊都在回答訪客心中的一個問題。以下列出那個問題，以及讓問題沒被回答的常見錯誤。

標題與一句話簡介

問題是「這是什麼」。一句話講清楚它做什麼、給誰用：「一個把 CSV 匯出檔轉成易讀 Markdown 報表的命令列工具。」

常見錯誤是講怎麼做的，而不是做什麼。沒有人為了知道你用哪個框架才點進來。

徽章

問題是「這專案還活著嗎」。一顆綠色建置徽章加上最近的版本號，半秒內就回答完。

常見錯誤是排上九顆徽章。超過四顆就不再是訊號，只是把簡介擠出第一屏的裝飾品。

安裝

問題是「我要怎麼拿到它」。一段可複製的圍籬程式碼，前面不要鋪陳。有前置需求就在區塊上方用一行寫完。

常見錯誤是把指令埋進整段文字裡。人們在掃描那個灰色方塊，不是在讀動詞。

使用方式

問題是「用起來長什麼樣」。給出最小但確實有作用的範例，再把輸出貼出來。

常見錯誤是列了一堆參數卻沒有範例。看過能跑的程式碼的人會自己去找參數；只看到參數的人通常就離開了。

設定

問題是「我能改嗎」。選項、型別、預設值、作用，四欄表格最快，因為讀者會沿著第一欄找那個只記得一半的名稱。

常見錯誤是預設值早就過期。改版時只來得及更新一個地方的話，就更新這張表。

貢獻與授權

貢獻回答「我能幫忙嗎」。兩行就夠：歡不歡迎 pull request，以及開大型 PR 前該做什麼。更長的規範放進獨立的 CONTRIBUTING.md。

授權回答「公司能用嗎」。寫出授權名稱並連到檔案。不寫並不等於中立，因為沒有授權時，法律預設是任何人都不得使用你的程式碼。

小專案用的精簡 README

多數儲存庫不需要九個區塊。一支腳本、一份設定檔倉庫，或一個週末做出來的小東西，用下面這種你真的維護得下去的版本更合適：

# csv2md

Turns a CSV file into a Markdown table. No dependencies.

## Install

```bash
pip install csv2md
```

## Use

```bash
csv2md data.csv > report.md
```

## License

MIT

什麼時候長版範本反而多餘

• 專案根本沒有選項。只有一列的設定表格是雜訊，一句話講完就好。
• 使用者只有你自己。私人儲存庫的貢獻說明只會放到過期，而且沒人會讀。
• 這是示範、分支或課堂作業。標題、一句話、怎麼執行，就結束了。
• 真正的文件在別的地方。那 README 就是路標：描述專案，連到文件網站。

注意：不要把還留著佔位文字的範本直接推上去。一份寫著「Project Name」的 README，等於告訴訪客這專案第一天就被放棄了。

什麼樣的 README 真的有人讀

讀者只給一份 README 幾秒鐘就做決定。撐得過那次掃描的，是下面幾個習慣。

• 先講它做什麼，不要先講怎麼做的。「把 CSV 轉成 Markdown 表格」能換到注意力；「用 Rust 和 Tokio 寫的」留到後面再說。
• 安裝指令要出現在第一屏。如果得先滑過一整段理念才看得到 pip install，很多人根本不會滑。
• 不只給指令，也給輸出。指令說要打什麼，輸出說會拿到什麼，後者才是讀者想像不出來的部分。
• 徽章控制在四顆以內。建置、版本、授權，最多再加測試覆蓋率。第五顆只會稀釋前面四顆。
• 當成寫給沒看過這個專案的人。半年後的你也算那種人。
• 跟畫面有關就放截圖。一張介面圖省下三段文字描述。
• 改功能的那次提交就順手改 README。寫錯的 README 比寫得少的更糟，因為錯誤的步驟會實實在在浪費讀者的時間。

拿自己的檔案做這個測試

用陌生人的眼光只讀第一屏，回答三個問題：這是什麼、怎麼安裝、用起來長什麼樣。任何一題答不出來，就把那段往上搬。

把 README 的格式寫好

README 就是一份 Markdown 檔，所以它的每個毛病都是 Markdown 的毛病。範本裡的每個部分，各自依賴一種語法。

架構與程式碼

標題用單個 #，區塊用 ##，標題語法專頁也說明了為什麼跳級會破壞 GitHub 依標題建立的大綱。安裝與使用指令要放進標了語言的圍籬區塊，bash 和 js 才有語法上色，細節都在程式碼區塊專頁。

清單、表格與圖片

功能條列就是一般的無序清單，清單專頁的巢狀規則值得花一分鐘，子清單被壓平幾乎都出在那裡。設定選項最適合用管線表格，上面範本的對齊冒號寫法，表格專頁有完整說明。

截圖和徽章共用同一套圖片語法，細節在圖片專頁；只需要那一行的話，Markdown 怎麼插入圖片就是最短的答案。徽章其實是包在連結裡的圖片。

方言與長檔案

GitHub 渲染的是 GitHub 風格 Markdown，待辦清單、刪除線與表格都能用，寫 README 就照這個方言寫。超過大約一千字時，用目錄產生器做一份目錄，不要手動維護錨點。

這些語法還很陌生的話，語法速查是最快的索引，完整 Markdown 指南會依序帶你走一遍。

檔案該放哪裡，又該怎麼檢查

檔名和位置，正是讓它自動被渲染的關鍵。

• 檔名取 README.md。主檔名全大寫，副檔名 .md 小寫。readme.md 也讀得到，但大寫是慣例，也會排在資料夾清單最前面。
• 放在儲存庫根目錄。代管平台先看那裡。放在 docs/ 或 .github/ 底下也算數，但根目錄那份優先。
• 每個資料夾都可以有一份。子資料夾的 README 會在有人瀏覽該資料夾時顯示，用來說明一整包範例很划算。

推上去之前先檢查

寫的時候在編輯器裡看預覽；同事丟一份檔案給你審，就用 Markdown 檢視器打開它。

推上去之後記得看一眼渲染後的頁面。相對路徑的圖片最常陣亡：在你電腦上讀得到的截圖，在專案頁面上仍可能 404，因為路徑是相對於儲存庫解析的。