[[392674]]

【51CTO.com快譯】在移動APP、Web應用、桌面程序、以及JavaScript庫的開發領域中，文檔在確保產品服務的成功交付方面起著至關重要的作用。但是，如果您曾經做過文檔相關工作，那么您一定會同意我的看法：文檔準備幾乎是大多數開發人員最不喜歡從事的工作之一。

對于開發人員而言，與編寫代碼之類的本質工作不同，他們需要交付出清楚易懂的文檔，甚至可以讓讀者對其易于交流和共享。也就是說，他們應當跳出一直以來能讓機器理解的代碼思維，并轉換為使用能讓人類理解的表達方式。

好文檔對于用戶的幫助

顯然，文檔可以幫助讀者理解代碼的工作原理。但是許多開發人員往往會陷入“知識陷阱”--錯誤地認為讀者也和自己一樣能夠精通目標代碼。因此，他們在準備文檔時，可能會跳過許多要點，而且并非從基礎開始說起。如果讀者了解相關編程語言，尚可弄清來龍去脈，否則全靠自行摸索，很容易會不知所終。

通常，那些可供用戶使用的文檔需要展示一些實際使用的案例，或是如何使用軟件產品的步驟。為了讓讀者能夠盡快上手，開發者應盡量使用那些用戶友好的詞語，而非各種專業的術語來進行表述。如果他們可以在此基礎上再提供一些實用的例子，則會更受歡迎。

同時，良好的文檔布局設計，也可以幫助用戶快速地跳轉到實際所需的部分。在此方面，Bootstrap和WordPress的文檔《WordPress的第一步》都是非常好的示例。

好文檔對于其他開發者的幫助

誠然，每個開發者都有自己的編程風格，但是在團隊合作中，我們也經常需要與其他隊友共享代碼。那么，為了就某項標準達成共識，團隊中的每位開發者都應當遵守相同的編程規范。而此類規范，往往是建立在頒發統一的文檔中，可供大家參考和遵循。

與最終用戶文檔不同的是，此類文檔通常需要清晰地描述諸如：代碼的命名規則，如何才能構造出特定的功能性頁面，以及其API如何與代碼示例協同工作之類的技術過程。此外，我們還應該編寫出代碼的內聯文檔(或稱為注釋)，來描述代碼的功用。

同時，如果將來有新的成員加入團隊，此類文檔也能夠大幅減少對其培訓的時間，我們不必和他們逐條討論代碼的細節。

好文檔對于自己的幫助

在程序開發領域有個十分有趣的現象：時隔幾年、甚至幾個月后，開發人員可能一時無法理解自己編寫過的代碼段，而需要花費一定的時間重新研讀。

因此，在編寫代碼的過程中順手記錄下相關注釋，將有助于您快速地回想起當時在鍵入此段代碼時，背后的編程思想與邏輯，從而能夠立即對其予以改進，或將其運用到其他類似的應用場景中。

好文檔的構成要素與實踐

下面，我將和您討論有助于您構建與開發出優秀文檔的五項實踐：

1.永遠不要假設

不要假設你的用戶已經知道了什么、以及他們需要知道什么。也就是說，無論受眾將對您的代碼具有何種熟練程度，都請您從頭開始、從基礎開始陳述。

例如，您構建了一個jQuery插件，那么就可以參照如下SlickJS的文檔，展示如何構造HTML，在何處放置CSS和JavaScript，如何初始化jQuery 的最基礎插件，以及在完成各種元素添加后，如何顯示完整的最終標記。

可見最重要的是，文檔的編寫思路應當從用戶的角度出發，而不是站在開發者的角度思考。只有從這種方式來組織您的文檔，才能讓更多的人愿意讀，也讀得懂。

2.遵守標準

在為代碼添加內聯文檔時，請參照對應編程該語言的相關標準，清楚地描述每個函數、變量、以及函數返回值的預期。在此，您可以參照如下PHP內聯文檔的示例。

如果您想了解更多有關不同編程語言的內聯文檔格式，請參考如下鏈接：

• PHP：WordPress的PHP文檔標準
• JavaScript：UseJSDoc
• CSS：CSSDoc

此外，如果您正在使用的SublimeText(譯者注：一款用于代碼標記的文本編輯器)，我建議您安裝DocBlockr(https://github.com/spadgos/sublime-jsdocs)，它能夠將內聯文檔巧妙地預填充(pre-populate)到您的代碼中。

3.圖形元素

相對于文本信息，人們更容易接受圖形元素，畢竟誰不喜歡“有圖有真相”呢?圖文并茂的文檔，尤其適用于那些用圖形化界面構建的軟件。您可以添加諸如箭頭、圓圈、以及任何可以引起用戶注意的指引性元素，來協助用戶弄清具體操作步驟，而無需進行任何猜測。

下圖是一個名為Tower應用示例。它有效地運用了一種讓人一目了然的表現方式，展現了其基本的操作方法。這顯然比純文本或命令行的表述，要更容易被理解一些。

4.分段

您可以考慮將文檔中的一些內容打包、并放置在某個標題條目、或表格的某個單元格中。據此，我們不但能夠變長為短，而且同樣可以方便用戶在瀏覽了標題條目后，快速地跳轉到想要閱讀內容處。

此類文檔的制作步驟通常是：先添加言簡意賅的標題目錄，然后將文檔分門別類地拆分為不同的專題部分，最后將每個部分與相關的標題對應起來。下圖是Facebook的一個結構良好的文檔示例，我們只需在右側目錄單擊要查閱的標題，左邊會立刻自動定位到相應的內容。

5.修訂和更新

最后，請在完成文檔時，認真審閱文字、圖表、甚至是各種表述上的錯誤。同時，在對應的軟件、產品、以及代碼庫發生重大變更時，也請及時地修訂對應的文檔。顯然，如果您的文檔無法保持定期或及時更新的話，那么它們不但會無法及時地為用戶提供幫助，甚至會對用戶起到誤導的作用。

原文標題：The Importance of Documentation for Web Developers，作者：Thoriq Firdaus

【51CTO譯稿，合作站點轉載請注明原文譯者和出處為51CTO.com】