[譯] 如何寫出優雅且有意義的 README.md

• 原文地址：How to Write Beautiful and Meaningful README.md
• 原文做者：Divyansh Tripathi [SilentLad]
• 譯文出自：掘金翻譯計劃
• 本文永久連接：github.com/xitu/gold-m…
• 譯者：Jessica
• 校對者：Vito,Hsu Zilin

如何寫出優雅且有意義的 README.md

寫出一個超棒的 Readme 文件的小技巧（以及爲何 README 很重要）

做爲開發人員，咱們對代碼以及項目中的全部細節都信手拈來。然而咱們中的一些人（包括我在內）就連在網絡社區中的軟技能都缺少。

一個開發人員會花一個小時來調整一個按鈕的 padding 和 margin。卻不會抽出 15 分鐘的來完善項目的 Readme 文件。

我但願大家大多數人已經知道 README 文件是什麼，它是用來作什麼的。可是對於萌新來講，我仍是會盡量地來解釋它究竟是什麼。

什麼是 Readme.md？

README（顧名思義：「read me「）是啓動新項目時應該閱讀的第一個文件。它既包含了一系列關於項目的有用信息又是一個項目的手冊。它是別人在 Github 或任何 Git 託管網站點，打開你倉庫時看到的第一個文件。

你能夠清楚地看到，Readme.md 文件位於倉庫的根目錄中，在 Github 上的項目目錄下它會自動顯示。

.md 這個文件後綴名來自於單詞：markdown。它是一種用於文本格式化的標記語言。就像 HTML 同樣，能夠優雅地展現咱們的文檔。

下面是一個 markdown 文件的例子，以及它在 Github 上會如何渲染。這裏，我使用 VSCode 預覽，它能夠同時顯示 markdown 文件渲染後的預覽。

若是你想要深刻了解這門語言，這裏有一個官方的 Github Markdown 備忘錄。

爲何要在 Readme 上花時間？

如今咱們談正事吧。你花了幾個小時在一個項目上，你在 GitHub 上發佈了它，而且你但願遊客、招聘人員、同事、（或者前任？）看到這個項目。你真的認爲他們會進入 root/src/app/main.js 來查看你的代碼的邏輯嗎？真的會嗎？

如今你已經意識到這個問題了，讓咱們看看如何解決這個問題。

爲你的組件生成文檔

除了項目的 Readme 以外，記錄組件對於構建易於理解的代碼庫也很重要。這使得重用組件和維護代碼變得更加容易。好比，使用像Bit (Github) 這樣的工具，來爲在 bit.dev 上共享的組件自動生成文檔。（譯者注：這裏是做者在打廣告）

團隊共享可重用的代碼組件 · Bit

描述你的項目！（技巧說白了就是）

爲你的項目寫一個好的描述。僅出於建議，您能夠將描述的格式設置爲如下主題：

• 標題（若是能夠的話，提供標題圖像。若是你不是平面設計師，請在 canva.com 上進行編輯）；
• 描述（用文字和圖片來描述）；
• Demo（圖片、視頻連接、在線演示 Demo 連接)；
• 技術棧；
• 你項目中須要注意的幾個陷阱（你遇到的坑、項目中的獨特元素）；
• 項目的技術說明，如：安裝、啓動、如何貢獻；

讓咱們深刻探討技術細節

我將使用個人這個項目做爲參考，我認爲它是我寫過甚至遇到過的的最漂亮的 Readme 文件之一。你能夠在這裏查看它的 Readme.md 文件的代碼: silent-lad/VueSolitaire

使用鉛筆圖標來顯示 markdown 代碼：

1. 添加圖片！拜託!

你可能對你的項目記憶猶新，可是你的讀者可能須要一些項目演示的實際圖片。

例如，我製做了一個紙牌項目，並在 Readme 文件中添加了圖像做爲描述。

如今你可能想要添加一個視頻描述您的項目。就像我項目裏那樣。可是，Github 不容許在 Readme 文件中添加視頻。那…該怎麼辦呢？

…咱們可使用 GIF

GIF 也是一種圖片，Github 支持咱們將它放在 Readme 文件中。

2. 榮譽勳章

Readme 文件上的徽章會使遊客有必定的真實感。您能夠從下面的網址，爲您的倉庫設置自定義或者常規使用的盾牌（徽章）：https://shields.io

你還能夠設置個性化的盾牌，如倉庫的的星星數量和代碼百分比指標。

3. 增長一個在線演示 Demo

若是能夠的話，請託管你的項目，並開啓一個正在運行的演示 demo。以後，將這個演示連接到 Readme 文件。你也不知道可能會有多少人來「把玩」你的項目。另外，招聘人員只喜歡能夠在線演示的項目。它代表你的項目不只僅是放在 Github 上的代碼，而是確實跑起來業務。

您能夠在 Readme 中使用超連接。好比在標題圖片下面提供一個在線演示連接。

4. 使用代碼樣式

Markdown 提供了將文本渲染爲代碼樣式的選項。所以，不要以純文本形式編寫代碼，應該使用 `（反單引號）將代碼包裹在代碼樣式中，例如 var a = 1;。

Github還提供了指定代碼編寫語言的選項，這樣它就可使用特定的文本高亮來提升代碼的可讀性。你只須要這樣使用：

```{代碼語言}<space>{代碼塊}```

{ ``` } —— 三個反單引號用於多行代碼，同時它還容許你指定代碼塊的語言。

使用代碼高亮：

不使用代碼高亮：

5. 使用 HTML

是的，你能夠在 Readme 裏使用 HTML。儘管並非 HTML 裏全部的功能均可以使用，但大部分能夠。雖然你最好是隻包含 markdown 的語法，但一些功能，如居中圖像和居中文本是隻能用 HTML 實現的。

6. 有創造性

剩下的就交給你了，每一個項目都須要不一樣的 Readme.md 文件和不一樣類型的描述。可是請記住，你在 Readme 文件上花費的 15 —— 20 分鐘可能會對你 Github 的訪問者數量產生巨大的影響。

僅供參考，這裏有一些帶 Readme 的項目：

• silent-lad/VueSolitaire
• silent-lad/Vue2BaremetricsCalendar

瞭解更多

• 如何在項目和應用之間共享 React UI 組件
• 2020 年的 13 個頂級 React 組件庫
• 2020 年的 11 個頂級 React 開發人員工具

若是發現譯文存在錯誤或其餘須要改進的地方，歡迎到 掘金翻譯計劃 對譯文進行修改並 PR，也可得到相應獎勵積分。文章開頭的 本文永久連接 即爲本文在 GitHub 上的 MarkDown 連接。

---

掘金翻譯計劃 是一個翻譯優質互聯網技術文章的社區，文章來源爲 掘金 上的英文分享文章。內容覆蓋 Android、iOS、前端、後端、區塊鏈、產品、設計、人工智能等領域，想要查看更多優質譯文請持續關注 掘金翻譯計劃、官方微博、知乎專欄。