《編寫README文檔》課程學習筆記

01-27

什麼是文檔

什麼是菜譜：

菜譜是一種記錄烹飪方法的文檔。
幫助我們了解需要的食材以及廚具的用法。
沒有這份文檔（菜譜），即使材料齊備，也不能做出菜品來。

技術文檔存在的意義與菜譜類似：

技術文檔是一種記錄使用代碼方法的文檔
幫助我們理解代碼
離開它，開發者無法獲知使用別人代碼的方法，可能都不知道如何運行它

文檔是寫給誰看的

好的技術文檔並不枯燥或難以編寫，有時候會以指南和教程的形式呈現，沒有人規定文檔應該是什麼樣的不該是什麼樣子的。

首先要知道文檔是寫給人看的，幫助我們理解代碼。舉個栗子，如果你在維護一個大型開源庫，好的文檔就非常重要，它直接決定項目對使用者和貢獻者的吸引力。如果你的文檔足夠好，人們就樂意在自己項目中使用你的庫。

事實上，文檔的閱讀對象可以是所有人，甚至包括你自己。

如何使用文檔

工程師每天都會用到文檔，涉及各類第三方庫和工具。在接觸新的文檔時，會在文檔中找到實際的例子。

沒有文檔會怎麼做：

會考慮棄用這個庫
使用文檔化更好的庫來代替
如果這個庫非常重要，也會考慮寫內部文檔

沒有文檔，如何去理解代碼：

投入大量時間去研究源代碼
用調試器監視程序運行
引入其他工具進行分析

沒有文檔，你甚至不知道你當時寫代碼在想什麼。總之，沒有文檔是件痛苦的事。

README簡介

我們都知道了編寫項目文檔的重要性，但那些項目文檔都非常龐大，這對於小型項目就不太合適。你想，我們只需一張食譜的時候何必寫一本菜譜出來呢。

事實上，有一種適用於小型項目的文檔形式，叫做README文件。該文件包含著同目錄下其他文件的信息，它通常用全大寫命名（README.md)來提醒用戶閱讀。

README的構成

readme要以精簡的方式向用戶傳遞信息，要牢記我們是為讀者而寫的。

開始是標題和說明，一兩句話就好，要確保清晰準確地表達項目內容。還記得前面說過，沒有人規定文檔應該怎麼寫。你自己選擇加入你認為必要的信息，對於用戶難以理解的部分可以詳細寫下。必要時引入示例代碼，展示代碼的正確用法。

記錄不斷擴大的代碼庫

在代碼量增長的過程中，你可能需要重新評估哪些信息應包含到文檔中。

先來看看readme的常見部分及若干用例。

我們應把項目潛在貢獻者需要了解的內容寫到readme里，補充上希望貢獻者了解的信息，這能給他們帶來很多便利。有一些類似代碼檢查的服務，能為你的resdme引入名為shields的特殊標記。這些工具由第三方提供，幫助用戶了解有關代碼信息。

用markdown編寫README文檔

readme可以用各種文件格式來寫

為什麼用markdown來編寫文檔：

排版後的文字非常適於快速閱讀
實現快速方便的內容排版
眾多開發者聚集的網站，如GitHub，stack overflow等都支持markdown

Markdown 基礎知識

Markdown 是一種輕型標記語言，經常用於 README 的編寫（但是也有用其他語言寫的！）。它非常簡單，大部分語法都很直觀。

與 HTML 文件應使用 .html 擴展名來保存類似，Markdown 文件應該使用 .md 擴展名來保存。

設置文本加粗

要將文本設置為粗體，請用兩個星號將其括起。因此，這行代碼：

Isnt today a **wonderful** day? n

會顯示為：Isnt today a wonderful day?

這比 HTML 中的 <strong> 標記更易讀，還能少打好多字元。

設置文本斜體

要將文本設置為斜體，請在文本兩旁添加下劃線。因此，這行代碼：

And in that moment I thought to myself: _Did I turn off the stove?_ n

會顯示為：And in that moment I thought to myself: Did I turn off the stove?

與上一個示例相似，這樣的代碼更接近自然語言，原始文檔瀏覽起來非常方便。

標題順序

標題更簡單！對於 h1 到 h6 標籤，你只需要在文本前添加 #。Markdown 會根據 # 的數量生成相應的標題。例如：

## This is an h2.n### This is an h3.n

#號越多，字體越小。

更多Markdown語法可在網上搜到更完整的文章

總結

現在你能夠給代碼編寫文檔，使用Markdown編輯README文件。好的代碼不是能運行就可以了，你需要讓它易於使用、易於維護。編寫文檔，就是以人為中心去編寫另一種意義的代碼，牢記這點會使你成為一名更好的開發者。總之，在做項目的過程中要編寫和更新文檔。

課程鏈接：編寫 README 文檔