目錄
概述
想像一下，你開發了一款功能強大的軟體產品，卻因為缺乏完善的文件而無人問津，甚至無人知曉它的存在。不幸的是，這樣的計畫比比皆是。
你的不一定非得是其中之一。
我之前發表過一篇文章《 每個 GitHub 專案的最後 1%：正確密封》 ，其中 README 文件被列為首要事項。沒錯，它就是這麼重要，這也是我決定深入研究這個主題的原因。
如果你是軟體工程師，那麼掌握撰寫規格文件的方法就是你最重要的技能之一。千萬不要忽略它，也不要把它當成可有可無的東西。
沒錯，寫程式碼確實更有趣。但是，事後回頭去理解自己當初寫了什麼（以及為什麼這麼做），卻沒有任何參考資料，遠不如事先寫好幾條清晰的筆記來得有趣。
如果你希望自己的作品得到認可、使用、貢獻，甚至獲得點贊，那麼文件就不是可有可無的。它是人們首先看到的內容之一，而且往往是他們留下或離開的關鍵因素。
但本文並非探討文件的整體概念，文件是一個非常龐大的主題，值得深入剖析。文件有很多不同的類型，每種類型都有其獨特的用途。
在這裡，我們將重點介紹最重要的部分： README 。
自述文件永遠不可能完美無缺。
在我職業生涯中，我見過各種各樣的README文件。有些很好，有些不太好，有些則接近完美。
但有一點始終不變：有一個包含一些有用資訊的 README 文件，總比完全沒有 README 文件要好得多。
凡事總要有個開始。完美並非一蹴而就，而是需要隨著時間的推移逐步實現的。
我從事軟體工程工作近十年了，即使到了今天，我仍然會審視自己的README文件，覺得它們可以更清晰、更一致，或者乾脆做得更好。你永遠不會對自己的文件撰寫完全滿意，而這正是關鍵所在。
它就像你的程式碼一樣，需要不斷改進。
在本文中，我將逐一介紹 README 文件中的重要部分，並解釋每個部分的重要性。
最後，我還會提供一個現成的 README 模板，您可以直接使用並根據自己的專案進行修改。
README 文件的主要用途
README 的主要目的是快速引導使用者了解有關儲存庫的基本資訊。
README 文件應該包含足夠的訊息，讓其他人能夠理解專案的內容、如何運作以及如何貢獻程式碼。並非所有資訊都需要放在 README 文件中，試圖涵蓋太多內容只會讓文件更難閱讀。
之所以存在不同類型的文件，是有原因的。每種文件都有其特定的用途，而 README 文件只是入口點，並非整本手冊。
一個好的 README 文件始於一個合理的結構。
README 文件通常以 Markdown 編寫，Markdown 已成為通用格式，原因有幾個：它簡單、支援廣泛、易於學習，並且足夠靈活，幾乎可以涵蓋 README 中所需的一切。
如果你之前從未使用過 Markdown，不妨先看看快速入門指南。不到半小時，你就能學會編寫優秀的 README 文件所需的一切。對於更進階的內容，你以後可以隨時查閱官方文件。
關鍵在於：不要用純文字編寫 README 文件。純文字不僅難以閱讀，而且擴展性很差。相反，請使用 Markdown 的特性，這不僅能使文件內容豐富，還能使其簡潔、結構清晰、易於瀏覽。
README 文件的基本章節
好了，現在是時候了解 README 文件中應該包含的基本部分了。
但要記住的關鍵一點是：這並非一份完整的清單。每個專案都各不相同，您的 README 文件也應體現這一點。除了這些核心部分之外，您可能還需要一些特定於您專案的自訂部分，因此不要局限於此清單。
此外，並非每個章節在任何情況下都是必要的。如果您正在建立一個簡單的「Hello World」等級的應用程式，則無需過度思考或包含本文提到的所有內容。本文的目標是涵蓋對大多數實際專案而言有意義的章節。
如果您認為我遺漏了什麼重要的東西，請隨時在評論中分享您的經驗，這對我以及更廣泛的開發者社群都很有價值。
以下是我的清單：
標題和引言
在深入探討專案細節之前，重要的是從最基本的要素入手：標題和簡短描述。
這就是吸引讀者註意力的關鍵。正如你可能知道的，第一印象至關重要。如果你想讓讀者繼續閱讀，這部分內容將決定他們是否會繼續閱讀。
您還可以透過加入視覺元素（例如徽標、標籤或專案截圖）來增強此部分的吸引力。例如，首頁、儀表板或任何看起來簡潔美觀的介面都非常適用。
以下是我其中一個專案的範例： Sunday DEV Drive 。
記住，這部分內容是整個專案的主海報。務必確保它清晰、有效且引人注目，因為它通常是人們首先看到的內容，並為後續所有內容定下基調。
它不僅可以是視覺上的，還可以是功能性的。您可以加入一些有用的連結，例如演示、影片教程、文章或其他任何相關資源，幫助人們更快地了解您的專案。
目錄
無論何時我會寫任何類型的結構化內容，無論是文件、README、文章或任何類似內容，我總是盡量包含目錄。
這是文件中最被低估和最少被利用的部分之一。我不會說它在任何情況下都至關重要，但它確實能大大提昇文件的清晰度和結構性。
你可以把它想像成電影的片頭字幕。電影本身可能很精彩，但片頭字幕已經讓你大致了解了演員陣容和劇情走向。它們在故事正式開始前就交代了背景。
目錄對你的專案也起到同樣的作用。它可以幫助讀者快速了解專案內容，並直接跳到他們感興趣的部分。
以下是我其中一個專案的範例： NoteRunway 。
此外，您還可以為每個部分加入連結，以便用戶可以輕鬆瀏覽 README 文件，而無需滾動和搜尋他們需要的內容。
關於
在這裡，你可以開始正式描述你的專案：它是什麼，它的功能是什麼，以及它如何運作（概括而言）。重點突出關鍵要點和核心理念，但暫時不要深入探討實現細節，這些內容稍後再談。
以下是我另一個專案中的一個例子：金屬鳥手錶。
特徵
現在是時候詳細展開一下，開始談談你的專案支援的主要功能了。
本部分通常有兩種結構方式。您可以採用簡單的表格形式，列出每個功能及其描述；或者，如果您想提供更多背景資訊和細節，也可以為每個功能使用子標題。
以下是我「金屬鳥手錶」專案中功能部分的範例：
儘管本節內容更加詳盡，但描述仍應保持概括性。目的是幫助讀者理解每個功能的作用，而不是實現方式。
大多數情況下，您不應該在此處包含實作細節。這些內容應該放在更詳細的文件或技術章節中。只有當它們對於理解功能本身至關重要時，才應該包含這些細節。
技術堆疊
README 文件中最重要的資訊之一就是技術堆疊。
首先，因為它代表了專案的建置模組。其次，許多開發者會積極尋找使用特定技術建構的專案，以便運用他們現有的技能做出貢獻。
所以，請明確說明您的專案是用什麼技術建構的，這有助於理解和發現。
以下是我NoteRunway專案的技術堆疊部分：
建築學
本節通常用於描述您的架構，從宏觀角度展示您的系統各個部分如何協同工作。
例如，這可能包括前端、後端、資料庫、快取層、外部服務、負載平衡器、防火牆以及與您的系統設計相關的任何其他內容。
使用 draw.io、Lucidchart 或類似圖表工具來視覺化架構也是一個很好的做法。視覺化表示幾乎總是比純文字解釋更容易理解，尤其對於更複雜的系統。
以下是金屬鳥類觀測計畫的架構圖：
如你所見，你不需要繪製過於複雜的圖表。大多數情況下，圖表越簡單越好。
清楚明了永遠是第一位的。保持簡潔易懂通常比增加不必要的複雜性更有價值，而且這也是其他開發者會一直欣賞的做法。
專案結構
這一點有點爭議，我在很多README文件中都沒看到，我也理解為什麼。你當然可以自己去研究原始碼，弄清楚它的結構，對吧？
但包含此部分的好處是，您可以清楚地描述關鍵資料夾和檔案、它們的功能以及它們的用途。
是的，寫起來可能有點繁瑣。但這絕對值得，不僅對未來的貢獻者有用，對你自己也是如此。當你以後再回到這個專案時，這部分內容可以讓你快速回顧整個專案的組織結構。
永遠要為未來的自己著想。
以下是Metal Birds Watch的一個例子：
入門
有些人喜歡稱之為“設置”，兩種說法都可以，本節的主要目的是清楚地解釋如何讓別人克隆你的存儲庫並在他們的本地計算機上進行設置。
這是 README 文件中最重要的部分之一，甚至可以說是最重要的部分，因為如果別人連你的專案都無法在本地執行，他們就無法為你的專案做出貢獻。
列出所有設定步驟後，務必親自測試。這有助於您及早發現遺漏的細節，並減少您和其他開發人員的挫折感。
本部分可以包括安裝所需的框架和相依性、設定外部服務帳戶（如果需要）、建立本機資料庫、配置環境變數以及在本機執行專案所需的任何其他步驟。
以下是來自NoteRunway應用程式的範例：
配置
這可以放在“入門指南”部分，但我有時會把它單獨列出來，因為配置是任何專案最基本的部分之一。
配置過程可能很快變得複雜繁瑣，因此務必在 README 文件中清晰地記錄配置資訊。這樣可以確保您始終了解每個參數的作用以及所有設定的完成方式。
您可以在此處新增任何類型的配置，例如環境變數、資料庫相關設定、功能標誌或儲存在雲端的外部 JSON 設定檔。
與高層次的概述部分不同，本部分將詳細介紹專案實際正確運作所必需的更實用的設定資訊。
以下是Metal Birds Watch的一個例子：
安全
安全性是文件編寫中需要重點關注的方面之一。
本節確保如果有人加入新功能或修改現有功能，他們能夠遵循既定標準，並了解整個專案中如何處理安全問題。
在這裡，您可以概述系統的關鍵安全注意事項，以免貢獻者意外引入漏洞或破壞現有的保護措施。
以下是來自NoteRunway應用程式的範例：
如何貢獻？
在這裡，您可以簡要描述專案的貢獻準則。
有時，尤其是在擁有數千名貢獻者的大型開源專案中，這種情況很難保持簡短。如果沒有明確的規則，事情很快就會變得一團糟。
但是，如果你的專案還處於早期階段，就沒必要把它搞得太複雜。通常，一些簡單的指導原則就足夠了，例如以下內容：
接下來是什麼？
讓讀者知道你的專案尚未完成，並且你計劃繼續支持它，並隨著時間的推移加入新功能，這是一種很好的做法。
在這裡你可以列出接下來的計劃。它不僅能展現專案的方向，還能為貢獻者提供思路，讓他們知道可以從哪裡開始貢獻力量。
舉個例子：
執照
許可資訊至關重要。它能讓人們了解他們可以對您的專案進行哪些操作以及需要滿足哪些條件。
您無需包含完整的許可協議文本或進行詳細解釋。大多數情況下，只需說明許可類型並提供許可文件連結即可，如下例所示：
致謝
對任何為你的專案做出貢獻的人，以及任何幫助你建立專案的工具、函式庫或資源，都表示感謝。
這是一個簡單但很有意義的部分，在適當的時候加入它總是一個好習慣。以下是來自NoteRunway應用程式的範例：
作者
最後但同樣重要的是，留下你的印記，因為你是這個專案的核心人物。是你把所有環節整合起來，讓它得以成功。
讓其他人更容易聯絡你、提出問題，甚至提議合作。
我的例子如下：
即用型模板
這裡有一個模板，您可以複製並貼上到您的專案中，並根據需要進行自訂。您可以隨意調整、新增章節或刪除任何不合適的內容。這旨在為建構結構良好的 README 文件提供一個靈活的起點。
# Title and Introduction (replace this with your project title)
---
## Table of Contents
---
## About
---
## Features
---
## Tech Stack
---
## Architecture
---
## Project Structure
---
## Getting Started
---
## Configuration
---
## Security
---
## How to Contribute?
---
## What's Next?
---
## License
---
## Acknowledgements
---
## Author結論
與軟體工程的大多數領域一樣，編寫好的 README 文件需要經驗和實踐。
但擁有一個堅實的起點可以讓整個過程更快、更直接。這就是我分享這篇文章的主要原因，希望你能快速上手，從一開始就能改進你的文件。
好的文件不僅能幫助他人，還能讓你成為更優秀的工程師。
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
