在移動、Web 和桌面應用或 JavaScript 庫的開發領域中，文檔在應用的成功之路上扮演着非常重要的角色。但如果你曾經編寫過文檔，就肯定會同意我的看法：編寫文檔是開發人員最不喜歡做的事情之一。
與編寫代碼（這是開發人員的本職工作）不同，文檔必須能被所有人輕鬆理解（這裏的所有人不僅是指開發人員，也包括缺乏技術背景的一般人）。從技術上講，我們必須將機器語言（代碼）翻譯成普通人都可以理解的語言，這種事情說起來容易做起來卻很難。
儘管這件事情可能會給你帶來很大的負擔，但是編寫文檔是很重要的環節，並且可以爲你的用戶、你的同事，尤其是你自己帶來諸多好處。
好的文檔可以幫助用戶
顯然，文檔可以幫助讀者 理解代碼的工作原理。但是許多開發人員有着錯誤的認識，那就是他們認爲軟件的用戶都是編程高手。在這樣的假設下，他們編寫的文檔可能只是薄薄的幾頁紙，從頭到尾跳過了文檔本應該包含的許多要點。如果你精通編程語言，那麼遇到問題還可以自己找出解決辦法。如果你並沒有那麼專業，那麼看文檔時很容易就會迷失方向。
供用戶使用的文檔通常包括使用實踐或“操作方法”的內容。爲一般用戶創建文檔時，經驗法則是 文檔應該清晰直觀。使用普通人也容易理解的詞彙要比使用技術術語或專業習語更合適。軟件的實際應用示例也是非常受用戶歡迎的。
良好的文檔佈局設計還可以真正幫助用戶輕鬆瀏覽文檔的各部分內容。在這方面一些很好的例子包括 Bootstrap 的文檔，和 WordPress 的“WordPress 的第一步”文檔，它們也都是我最喜歡的榜樣。
好的文檔可以幫助其他開發人員
每位開發人員都有自己的代碼風格。但在團隊合作中，我們經常需要與其他同事共享代碼。因此大家有必要 達成共識，形成一套標準，以使所有人保持一致。精心編寫的書面文檔會是團隊必要的參考。
但與最終用戶文檔不同，這類文檔通常會描述代碼命名約定之類的技術流程，展示開發人員應如何構造特定頁面，以及 API 如何工作，外加一些代碼示例。通常，我們還必須在代碼內編寫文檔（稱爲註釋），以描述所註釋代碼的作用。
此外，如果以後有新成員加入團隊，這類文檔可以是培訓他們的一種省時有效的方法，這樣你就不必爲新人一對一地講解代碼了。
好的文檔也可以幫助開發人員自己
關於編程的有趣之處在於，有時 甚至開發人員自己也不理解他們編寫的代碼。尤其是當開發人員幾個月甚至幾年都沒再碰過自己寫過的代碼時，他們突然回來看自己的作品會感到十分陌生。
如果出於某種原因，開發人員需要重新審閱以前的代碼，他們往往會懷疑自己在編寫這些代碼時到底在想些什麼。別驚訝：我以前就曾遇到過這種情況。在這種情況下，我肯定會希望自己給代碼寫下了良好的文檔。
給你的代碼寫好文檔的話，你就能夠快速深入到代碼的底層，不會有那麼多疑惑，從而節省許多時間。省下來的這些時間可以拿來完成更改工作。
好的文檔有哪些特性？
有幾個因素可以幫助你構建出良好的文檔。其中一些最重要的因素如下：
1. 永遠不要假設
不要以爲你知道的東西用戶也知道，或者他們很清楚自己應該瞭解的內容。無論用戶的熟練程度如何，總是 從頭開始解釋各種事情 是更好的選擇。
例如，如果你構建了一個 jQuery 插件，則可能會從 SlickJS 的文檔中汲取靈感。它介紹瞭如何構造 HTML、放置 CSS 和 JavaScript 的位置、從頭開始講解如何初始化 jQuery 插件，甚至還展示了添加所有這些內容後的完整最終標記，所有東西都寫得清清楚楚。
最重要的是，文檔應該是根據用戶而不是開發人員的思考過程來編寫的。以這種方式處理你自己的文檔，將爲你提供一個更好的視角來組織自己的代碼。
2. 遵守標準
在添加與代碼內聯的文檔時，請使用 代碼編程語言所期望的標準。 我們應該總是解釋每個函數、變量以及函數返回的值都是什麼意思。下面是一個很好的 PHP 內聯文檔示例。
/**
* Adds custom classes to the array of body classes.
*
* @param array $classes Classes for the body element.
* @return array
*/
function body_classes( $classes ) {
// Adds a class of group-blog to blogs with more than 1 published author.
if ( is_multi_author() ) {
$classes[] = 'group-blog';
}
return $classes;
}
add_filter( 'body_class', 'body_classes' );
以下是使用 PHP、JavaScript 和 CSS 的最佳實踐來格式化內聯文檔的一些參考：
如果你使用的是 SublimeText，我建議你安裝 DocBlockr，它將用內聯文檔巧妙地預填充你的代碼。
3. 圖形元素
文檔中應該多用圖形元素，它們比文本更直觀。這些媒介很有用，特別是當你使用圖形界面構建軟件時。你可以添加指向性元素，例如箭頭、圓圈或 任何可以幫助用戶直觀地弄清楚如何完成這些步驟的元素。
以下是 Tower 應用中的示例，你可以從中汲取靈感。它們很好地解釋瞭如何用優雅的方式來做版本控制工作，比純文本命令行更容易理解。
4. 分區
你可以考慮將文檔中的一些內容包裝在項目符號列表和表格中，因爲這樣可以讓用戶更容易瀏覽較長的內容，更方便快速定位。
添加目錄，並將文檔拆分爲一些容易理解的部分，同時要讓各個部分與接下來的內容保持關聯。內容應該簡短明瞭。以下是 Facebook 中一份組織良好的文檔示例。
我們可以點擊目錄元素，直接跳轉到對應內容。
5. 修訂和更新
最後，文檔寫好後要仔細查看文檔中是否有錯誤，並在必要時，或在產品、軟件或庫發生重大更改時修訂文檔。如果不隨產品一起定期更新，那麼你的文檔對任何人都是沒用的。