[[392674]]

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

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

好文檔對于用戶的幫助

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

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

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

好文檔對于其他開發(fā)者的幫助

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

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

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

好文檔對于自己的幫助

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

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

好文檔的構(gòu)成要素與實踐

下面，我將和您討論有助于您構(gòu)建與開發(fā)出優(yōu)秀文檔的五項實踐：

1.永遠不要假設(shè)

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

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

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

2.遵守標準

在為代碼添加內(nèi)聯(lián)文檔時，請參照對應(yīng)編程該語言的相關(guān)標準，清楚地描述每個函數(shù)、變量、以及函數(shù)返回值的預(yù)期。在此，您可以參照如下PHP內(nèi)聯(lián)文檔的示例。

如果您想了解更多有關(guān)不同編程語言的內(nèi)聯(lián)文檔格式，請參考如下鏈接：

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

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

3.圖形元素

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

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

4.分段

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

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

5.修訂和更新

最后，請在完成文檔時，認真審閱文字、圖表、甚至是各種表述上的錯誤。同時，在對應(yīng)的軟件、產(chǎn)品、以及代碼庫發(fā)生重大變更時，也請及時地修訂對應(yīng)的文檔。顯然，如果您的文檔無法保持定期或及時更新的話，那么它們不但會無法及時地為用戶提供幫助，甚至?xí)τ脩羝鸬秸`導(dǎo)的作用。

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

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