在移動、web和桌面應用或JavaScript庫的開發(fā)領域，文檔在決定應用的成功中扮演著重要的角色。但是如果您曾經(jīng)做過文檔，您會同意我的觀點，那就是文檔是開發(fā)人員最不喜歡做的事情。

與編寫代碼(這是開發(fā)人員簽約時要做的事情)不同，文檔必須容易被每個人消化。從技術上講，我們必須把機器語言(代碼)翻譯成人類可以理解的語言，這比聽起來要困難得多。

盡管編寫文檔真的很麻煩，但它很重要，它將為您的用戶、您的同事，特別是您自己帶來好處。

良好的文檔有助于用戶

顯然，文檔可以幫助讀者理解代碼是如何工作的。但是許多開發(fā)人員錯誤地認為軟件的用戶都是精通的。

因此，文檔可能是很薄的材料，跳過了很多從一開始就應該包含的基本內(nèi)容。如果你精通這門語言，你就能主動把事情搞清楚;如果你沒有，那么你就迷失了。

為用戶準備的文檔通常包括實際使用或“如何”。在為普通用戶創(chuàng)建文檔時，經(jīng)驗法則是它應該是清晰的。使用對人友好的詞語比使用技術術語或行話更可取。也將非常感謝真實的使用例子。

一個好的布局設計也能真正幫助用戶瀏覽文檔的每個部分，而不會使眼睛疲勞。一些很好的例子(也就是我最喜歡的)是Bootstrap文檔和WordPress的“使用WordPress的第一步”。

它可以幫助其他開發(fā)者

每個開發(fā)人員都有自己的編碼風格。但是，當涉及到團隊工作時，我們經(jīng)常不得不與其他隊友分享代碼。因此，有必要在一個標準上達成共識，以保持每個人在同一頁。一個適當?shù)臅嫖臋n將是團隊需要的參考

但與最終用戶文檔不同的是，該文檔通常描述技術過程，如代碼命名約定，展示如何構造特定頁面，以及API如何與代碼示例一起工作。通常，我們還必須編寫與代碼(稱為注釋)內(nèi)聯(lián)的文檔，以描述代碼正在做什么。

此外，在你的團隊有新成員加入的情況下，這個文檔可以是一種有效的培訓他們的方法，所以你不必讓他們1對1地運行代碼。

它也能幫助程序員自己

關于編碼的有趣之處在于，有時甚至開發(fā)人員自己也不理解他們所編寫的代碼。這在那些密碼幾個月甚至幾年都沒被碰過的情況下尤其正確。

突然出于某種原因需要重新訪問這些代碼會讓人想知道在他們編寫這些代碼時腦子里在想什么。別驚訝，我以前也遇到過這種情況。正是在這個時候，我希望我正確地記錄了我的代碼。

通過編寫代碼文檔，您將能夠快速地了解代碼的底層，而不會感到沮喪，從而為您節(jié)省了大量可以用于完成更改的時間。

什么是好的文檔?

有幾個因素可以幫助構建一個好的文檔。以下是一些最重要的問題:

1. 永遠不要認為

不要以為你的用戶既知道你知道什么，也知道他們想知道什么。不管用戶的熟練程度如何，從頭開始總是比較好。

例如，如果您構建了一個jQuery插件，您可以從SlickJS的文檔中獲得靈感。它展示了如何構造HTML，在哪里放置CSS和JavaScript，如何在最基本的級別初始化jQuery插件，甚至顯示添加所有這些東西后的完整最終標記，這是顯而易見的。

最重要的是，文檔是以用戶的思維過程而不是開發(fā)人員的思維過程來編寫的。用這種方式來處理你自己的文檔會讓你在組織你自己的作品時有一個更好的視角。

2. 遵循標準的

在添加與代碼內(nèi)聯(lián)的文檔時，使用語言所期望的標準。描述每個函數(shù)、變量以及函數(shù)返回的值總是一個好主意。下面是一個很好的PHP內(nèi)聯(lián)文檔示例。

以下是一些使用PHP, JavaScript和CSS的最佳實踐來格式化內(nèi)聯(lián)文檔的參考:

WordPress的PHP文檔標準

如果你正在使用SublimeText，我建議安裝DocBlockr，它將巧妙地用內(nèi)聯(lián)文檔預填充你的代碼。

3.圖形元素

使用圖形元素，它們比文本更好地表達。這些媒體非常有用，特別是當你構建帶有圖形界面的軟件時。您可以添加指向元素，如箭頭、圓或任何可以幫助用戶確定在何處完成這些步驟的元素，而無需猜測。

以下是來自Tower應用的一個例子，你可以從中獲得靈感。它們有效地解釋了版本控制是如何以一種令人愉快的方式工作的，這使得它比使用純文本命令行更容易理解。

4. 切片

您可以考慮將文檔中的一些內(nèi)容包裝在項目符號列表和表格中，這樣可以使用戶更容易瀏覽和閱讀較長的內(nèi)容。

添加一個內(nèi)容表，并將文檔分成容易理解的部分，但要保持每個部分與接下來的內(nèi)容相關。保持簡潔明了。下面是一個很好的Facebook文檔組織的例子。目錄表帶我們?nèi)ツ睦?，我們想跳躍到點擊。

5. 修改和更新

最后，檢查文檔中的錯誤，并在必要時或者在產(chǎn)品、軟件或庫發(fā)生重大變化時進行修改。如果您的文檔不定期與您的產(chǎn)品一起更新，那么它對任何人來說都是毫無用處的。