crafting-effective-readmes

打造有效的 README

概述

README 要回答目標對象會提出的問題。不同的對象需要不同的資訊——開源專案的貢獻者需要的背景知識，和未來的你打開設定資料夾時需要的內容截然不同。

永遠要問： 誰會讀這個，他們需要知道什麼？

流程

步驟 1：確認任務

問：「你正在處理什麼 README 任務？」

任務	時機
建立	新專案，還沒有 README
新增	需要記錄新的內容
更新	功能已變更，內容過時
審閱	檢查 README 是否仍然準確

步驟 2：任務專屬問題

建立初始 README：

1. 這是哪種類型的專案？（見下方專案類型）
2. 用一句話說明這個專案解決了什麼問題？
3. 最快能讓它「動起來」的路徑是什麼？
4. 有沒有值得強調的事項？

新增章節：

1. 需要記錄什麼？
2. 應該放在現有結構的哪個位置？
3. 誰最需要這項資訊？

更新現有內容：

1. 什麼東西變了？
2. 閱讀目前的 README，找出過時的章節
3. 提出具體的修改建議

審閱/刷新：

1. 閱讀目前的 README
2. 對照實際專案狀態（package.json、主要檔案等）
3. 標記過時的章節
4. 如果有「最後審閱」日期，更新它

步驟 3：永遠要問

草稿完成後，問：「有沒有其他需要強調或納入，而我可能遺漏的內容？」

專案類型

類型	目標對象	關鍵章節	範本
開源	貢獻者、全球使用者	安裝、使用方式、貢獻、授權	templates/oss.md
個人	未來的你、作品集瀏覽者	功能說明、技術棧、學習心得	templates/personal.md
內部	團隊成員、新進人員	設定、架構、操作手冊	templates/internal.md
設定	未來的你（困惑中）	這裡有什麼、為什麼、如何擴充、注意事項	templates/xdg-config.md

如果不確定，請詢問使用者。 不要預設所有專案都是開源。

必要章節（所有類型）

每個 README 至少需要：

1. 名稱 - 不言自明的標題
2. 說明 - 用 1-2 句話說明是什麼與為什麼
3. 使用方式 - 如何使用（範例很有幫助）

參考資料

• section-checklist.md - 依專案類型應包含哪些章節
• style-guide.md - 常見 README 錯誤與寫作指引
• using-references.md - 深入參考資料的使用指南