可以說，對於任何開源專案來說，最重要的文件就是自述文件。一個好的自述文件不僅告訴人們該專案的用途和用途，還告訴人們他們如何使用該專案並為其做出貢獻。
如果您在撰寫自述文件時沒有充分解釋您的專案的用途或人們如何使用它，那麼它幾乎違背了開源的目的，因為其他開發人員不太可能參與或為其做出貢獻。
TL;DR - 太長？跳到最後並使用我的模板。
什麼是自述文件？
本質上，自述文件是一個單一的文字檔案（ .txt或.md ），可作為專案或目錄的一站式文件。對於大多數開源專案來說，它通常是最明顯的文件和登陸頁面。即使自述文件的名稱全部大寫，也是為了吸引讀者的注意力並確保這是他們首先閱讀的內容。
有證據顯示自述文件的歷史可以追溯到 20 世紀 70 年代。我能找到的最古老的例子是 DEC PDP-10 計算機的自述文件，日期為 1974 年 11 月 27 日。儘管自述文件名稱的起源存在爭議，但最流行的兩種理論是：
-
帶有打孔卡的原始大型計算機的程式設計師會留下一疊帶有“READ ME！”的紙質指令。寫在前面。
-
這個名字是向劉易斯·卡羅爾的《愛麗絲夢遊仙境》致敬，其中主角愛麗絲發現了一瓶標有“喝我”的藥水和標有“吃我”的蛋糕，這使她的體型發生了變化。
自述文件中應包含哪些內容？
好的，那麼一個很棒的自述文件該包含什麼內容呢？作為起點，我建議您包括以下關鍵內容：
1. 命名事物
不要忘記為您的專案或功能命名。 GitHub 上有數量驚人的沒有名稱的專案。
2. 介紹或總結
寫一篇簡短的兩三行簡介，解釋你的專案的用途和用途。還要省略“簡介”、“摘要”或“概述”等標題 - 很明顯這是一個簡介。
3. 先決條件
在介紹之後立即加入一個部分，標題為列出任何想要使用該專案的人在開始之前可能需要的任何先決知識或工具。例如，如果它在最新版本的 Python 上執行，請告訴他們安裝 Python。這是一個例子：
Prerequisites
Before you continue, ensure you have met the following requirements:
* You have installed the latest version of Ruby.
* You are using a Linux or Mac OS machine. Windows is not currently supported.
* You have a basic understanding of graph theory.4. 如何安裝
提供安裝步驟！令人驚訝的是，我遇到的許多專案只提供基本的使用說明，並期望您神奇地知道如何安裝它。如果需要多個步驟，請確保將安裝分解為編號的步驟。
5. 如何使用該東西
新增使用者安裝專案後如何使用該專案的步驟。如果您認為有用，請確保包含使用範例和解釋命令選項或標誌的參考。如果您在單獨的文件或網站中有更高級的文件，請從此處連結到該文件。
6. 如何為事情做出貢獻
提供為專案做出貢獻的步驟。或者，如果您希望人們在向您的專案貢獻拉取請求之前閱讀它，您可能希望在單獨的文件中建立貢獻者指南，並從自述文件連結到該指南。
7. 加入貢獻者
在作者部分感謝為該專案提供幫助的任何貢獻者。這是一種很好的方式，讓開源感覺像是團隊的努力，並感謝每個花時間做出貢獻的人。
8. 加入致謝
同樣，如果您使用了其他人的作品（程式碼、設計、圖像等），並且該作品具有需要確認的版權，您可能需要在此處加入。您還可以感謝為該專案提供幫助的任何其他開發商或機構。
九、聯絡方式
您可能不想這樣做，因為您是一個非常注重隱私的人，但如果有人有疑問、想要與您合作或對您的專案印象深刻並為您提供工作機會，那麼將您的聯絡方式放在前面是有意義的中心。
10.新增許可證訊息
如果適用，您肯定希望包含許可證資訊。除非您提供此軟體，否則依賴第三方軟體的新創公司和其他公司不太可能能夠使用您的專案。請造訪Choosealicense.com或opensource.org ，以取得您可以使用的授權清單。
在您的自述文件中加入耀斑 🔥
如果您確實想讓您的自述文件脫穎而出並且看起來具有視覺吸引力，您可以執行以下操作：
-
新增徽標：如果您的專案有徽標，請將其新增至自述文件的頂部。品牌使專案看起來更專業並幫助人們記住它。
-
新增徽章或盾牌：您可以新增徽章和盾牌以反映專案的當前狀態、它使用的許可證以及它使用的任何依賴項是否是最新的。而且它們看起來很酷！您可以在Shields.io找到徽章清單或自行設計。
-
新增螢幕截圖：有時一個簡單的螢幕截圖或一組螢幕截圖可以表達的內容遠遠超過一千個單字。但請注意，如果您確實使用螢幕截圖，則每次更新專案時都需要更新它們。
-
使用表情符號？ ：現在很多專案似乎都使用表情符號，儘管是否使用它們取決於您。它們是為你的自述文件注入一點色彩和幽默的好方法，讓專案感覺更人性化。
如果您使用所有貢獻者來感謝貢獻，您可以使用他們的表情符號鍵來表示不同的貢獻類型：
* 🐛 for raising a bug
* 💻 for submitting code
* 📖 for docs contributions etc.
這是 GitHub 徽章或盾牌的樣子，供參考（毫無疑問您以前見過它們！）：
我的模板<a name="template"></a>
我建立了一個模板，涵蓋了本文中提出的大部分建議。請隨意分叉存儲庫，提出改進建議或根據自己的目的自訂它！您可以在 GitHub上找到我的模板。
資源
如果您需要更多有關自述文件的建議，我還推薦以下資源：
-
Daniel Beck 在 2016 年 Write the Docs 的演講「Write the Readable」 。
-
Lorna Jane Mitchell 在 API 文件 2019 中的演講「Github 作為登陸頁面」 。
-
查看 Franck Abgrall 的README 產生器。
原文出處：https://dev.to/scottydocs/how-to-write-a-kickass-readme-5af9
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式