[[392674]]

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

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

好文檔對(duì)于用戶的幫助

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

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

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

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

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

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

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

好文檔對(duì)于自己的幫助

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

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

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

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

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

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

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

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

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

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

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

• PHP：WordPress的PHP文檔標(biāo)準(zhǔn)
• JavaScript：UseJSDoc
• CSS：CSSDoc

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

3.圖形元素

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

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

4.分段

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

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

5.修訂和更新

最后，請(qǐng)?jiān)谕瓿晌臋n時(shí)，認(rèn)真審閱文字、圖表、甚至是各種表述上的錯(cuò)誤。同時(shí)，在對(duì)應(yīng)的軟件、產(chǎn)品、以及代碼庫發(fā)生重大變更時(shí)，也請(qǐng)及時(shí)地修訂對(duì)應(yīng)的文檔。顯然，如果您的文檔無法保持定期或及時(shí)更新的話，那么它們不但會(huì)無法及時(shí)地為用戶提供幫助，甚至?xí)?duì)用戶起到誤導(dǎo)的作用。

原文標(biāo)題：The Importance of Documentation for Web Developers，作者：Thoriq Firdaus

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