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

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

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

良好的文檔有助于用戶

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

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

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

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

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

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

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

此外，在你的團(tuán)隊(duì)有新成員加入的情況下，這個(gè)文檔可以是一種有效的培訓(xùn)他們的方法，所以你不必讓他們1對(duì)1地運(yùn)行代碼。

它也能幫助程序員自己

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

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

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

什么是好的文檔?

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

1. 永遠(yuǎn)不要認(rèn)為

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

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

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

2. 遵循標(biāo)準(zhǔn)的

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

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

WordPress的PHP文檔標(biāo)準(zhǔn)

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

3.圖形元素

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

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

4. 切片

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

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

5. 修改和更新

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