學(xué)習(xí)一個(gè)新的工具或者軟件茸俭，首選方法是閱讀開(kāi)發(fā)者寫的軟件文檔吊履，因?yàn)門A最清楚怎么回事；其次是閱讀最新的英文相關(guān)使用討論或者介紹调鬓，因?yàn)橹形牡暮芏噘Y料往往滯后艇炎；再次才是閱讀中文相關(guān)介紹，而且一定要謹(jǐn)慎參考認(rèn)真判斷腾窝。評(píng)判一個(gè)工具好壞的標(biāo)準(zhǔn)之一也是其文檔是否寫的足夠「好」缀踪。

因此無(wú)論是開(kāi)發(fā)者還是用戶，文檔都至關(guān)重要虹脯。那到底好的文檔需要包含哪些內(nèi)容或者應(yīng)該如何寫出一個(gè)盡量好的文檔呢驴娃？最近看到一篇英文博客：What nobody tells you about documentation ，以下為盡量保留作者原意的不完全翻譯版本供你參考循集。

寫在前面

無(wú)論你如何認(rèn)真地寫軟件文檔唇敞，它可能都對(duì)你的軟件起不到什么幫助，除非你掌握了正確的文檔寫作方法咒彤。為了寫好軟件文檔你需要了解一個(gè)秘密：「文檔」不是特指某一個(gè)內(nèi)容疆柔，而是有四個(gè)。

它們是：教程(tutorials)镶柱，操作指南(how-to guides)旷档，說(shuō)明(explanation ) 和技術(shù)參考(technical reference)。它們代表了四種不同的目的或功能并且需要用四種不同的方法來(lái)寫歇拆，了解這一點(diǎn)將有助于極大改進(jìn)大多數(shù)軟件的文檔彬犯。

一個(gè)軟件有多好并不重要，因?yàn)?strong>如果文檔不夠好查吊，很多人就不想使用它。

即使由于某種原因（沒(méi)有第二選擇）別人不得不用湖蜕，如果沒(méi)有規(guī)范良好的文檔逻卖，使用者也不會(huì)高效地或者按照開(kāi)發(fā)者想要的方式來(lái)使用。雖然幾乎每個(gè)人都明白這一點(diǎn)昭抒，每個(gè)人也都知道他們需要一個(gè)好的文檔并且試圖創(chuàng)建一個(gè)好的文檔评也，但是大多數(shù)人還是失敗了。這并不是因?yàn)樗麄儾粔蚺Χ且驗(yàn)闆](méi)有找到正確的方法灭返。

接下來(lái)我將解釋如何使你的文檔變得更好盗迟，不是更加努力而是通過(guò)正確的方式。所謂正確的方法其實(shí)就是更簡(jiǎn)單的方法：更容易編寫熙含，更容易維護(hù)罚缕。

The right way is the easier way - easier to write, and easier to maintain.

有一些非常簡(jiǎn)單的原則可以指導(dǎo)我們進(jìn)行文檔編輯，但似乎又像是一個(gè)秘密很少被人們提起和總結(jié)怎静。如果你能夠?qū)⑦@些原則付諸實(shí)踐邮弹，它就可以使你的文檔變的更好黔衡，進(jìn)而使你的項(xiàng)目、產(chǎn)品或團(tuán)隊(duì)更成功腌乡。

原則

好的文檔需要包含并圍繞其四個(gè)不同的功能進(jìn)行構(gòu)建：教程(tutorials)盟劫，操作指南(how-to guides)，說(shuō)明(explanation )和技術(shù)參考(technical reference)与纽。每一部分都有自身獨(dú)特的寫作模式侣签，使用軟件的人在不同的時(shí)間不同的情況下會(huì)需要這四種不同的文檔 。因此急迂，需要圍繞它們明確地來(lái)構(gòu)建文檔并且必須保持獨(dú)立和彼此不同影所。

教程

• 學(xué)習(xí)為導(dǎo)向(learning-oriented)
• 可以讓新手輕松入門
• 可以理解為是一節(jié)課

如果要打個(gè)比方，就像教小朋友怎么做飯

操作指南

• 目標(biāo)為導(dǎo)向(goal-oriented)
• 展示如何解決特定問(wèn)題
• 是一系列步驟

打個(gè)比方就是烹飪書中的一個(gè)食譜

說(shuō)明

• 理解為導(dǎo)向(understanding-oriented)
• 用來(lái)進(jìn)行解釋
• 提供各種相關(guān)的背景

打個(gè)比方就像是一篇關(guān)于烹飪歷史的文章

參考

• 信息為導(dǎo)向(information-oriented)
• 描述一個(gè)工具的系統(tǒng)方法
• 一定是準(zhǔn)確而且完整的

類比的話袋毙，可以參考百科全書中的文章

以上這種分類可以使開(kāi)發(fā)者和用戶明白哪些信息在哪里型檀。它告訴開(kāi)發(fā)者如何寫，寫什么以及在哪里寫听盖，使他們免于浪費(fèi)大量時(shí)間來(lái)嘗試將想要傳達(dá)的信息改為其他亂七八糟的形式胀溺，因?yàn)?strong>這四種文檔，每一種只有一個(gè)任務(wù)皆看。

如果這些文檔沒(méi)有明確地展現(xiàn)出自身用處和界限仓坞，想要維護(hù)一個(gè)良好的文檔就是非常困難的。每種類型的文檔要求都與其他三者不同腰吟。你一旦理解了這些結(jié)構(gòu)它就能成為一種非常有用的工具无埃，一方面你可以用它分析自己現(xiàn)有的文檔，另一方面可以了解需要采取哪些措施進(jìn)行改進(jìn)毛雇。

教程

教程是讓用戶通過(guò)一系列步驟來(lái)完成某個(gè)項(xiàng)目的課程嫉称。它是你的軟件所必須具備的，用來(lái)向初學(xué)者展示他們可以用它實(shí)現(xiàn)某些目的灵疮。教程完全以學(xué)習(xí)為導(dǎo)向织阅，進(jìn)一步講，他們的目標(biāo)是學(xué)習(xí)如何使用而不是了解你的項(xiàng)目震捣。

此時(shí)你是一個(gè)老師并對(duì)學(xué)生將要做的操作負(fù)責(zé)荔棉。在你的指導(dǎo)下學(xué)生將執(zhí)行一系列操作以達(dá)到目的。什么時(shí)候結(jié)束和進(jìn)行哪些操作都取決于你蒿赢，但決定一個(gè)初學(xué)者應(yīng)該做什么非常困難润樱，一方面這些操作和最終的結(jié)束點(diǎn)必須有意義，同時(shí)對(duì)于一個(gè)真初學(xué)者而言又要可以實(shí)現(xiàn)羡棵。

現(xiàn)在想想教孩子做飯的例子壹若。你教孩子做了哪道菜其實(shí)并不重要，重要的是讓孩子覺(jué)得做飯這件事很有樂(lè)趣并且有信心，同時(shí)還希望自己可以再來(lái)一次舌稀。通過(guò)孩子所做的事情啊犬，他將學(xué)習(xí)烹飪的一些重要事項(xiàng)并且將了解在廚房里使用餐具來(lái)處理食物是一種什么感覺(jué)。

使用軟件（做飯）是一個(gè)「手藝」問(wèn)題壁查。它的確是知識(shí)觉至，但它是一種實(shí)踐得來(lái)的知識(shí)。當(dāng)我們學(xué)習(xí)一項(xiàng)新的手藝或技能時(shí)睡腿，我們總是從實(shí)踐開(kāi)始语御。記住，完成教程后學(xué)習(xí)者應(yīng)該就能夠理解軟件本身和其余的那些文檔席怪。老實(shí)說(shuō)应闯，大多數(shù)軟件項(xiàng)目的教程都非常糟糕或者根本不存在教程。教程可以讓一個(gè)學(xué)習(xí)者變成你的用戶挂捻，錯(cuò)誤或缺少教程將阻止你的軟件獲取新用戶碉纺。不過(guò)好的教程很難寫，它需要對(duì)初學(xué)者有用有意義易于參照且夠強(qiáng)大刻撒。

如何寫出好教程

允許用戶通過(guò)實(shí)際操作進(jìn)行學(xué)習(xí)

小時(shí)候我們都是通過(guò)實(shí)踐和嘗試來(lái)學(xué)習(xí)東西骨田，比如說(shuō)話或走路。在你的軟件教程中學(xué)習(xí)者需要有事可做声怔，而且他們所做的事情需要涵蓋這個(gè)工具大量的操作态贤，從最簡(jiǎn)單的操作開(kāi)始再到更復(fù)雜的。

讓用戶走出第一步

不管初學(xué)者的第一步是復(fù)制粘貼醋火，還是不像一個(gè)有經(jīng)驗(yàn)的用戶那樣操作悠汽，或者甚至不是一個(gè)“正確的”使用方式，這些都是可以接受的芥驳。初學(xué)者的教程與最佳實(shí)踐手冊(cè)不同柿冲，教程的目的是讓學(xué)習(xí)者開(kāi)始他們的旅程而不是讓他們到達(dá)目的地。

確保教程可以運(yùn)行

作為老師你的一個(gè)重要工作是激發(fā)初學(xué)者的信心兆旬，有很多途徑可以促成這一點(diǎn)姻采，比如友好的語(yǔ)氣和富有邏輯性的內(nèi)容與資料等等。但最重要的是你要求初學(xué)者做的事必須確實(shí)可以做到爵憎。學(xué)習(xí)者需要看到你要求他們采取的操作會(huì)產(chǎn)生你答應(yīng)他們會(huì)有的效果。如果學(xué)習(xí)者的操作產(chǎn)生報(bào)錯(cuò)或有了一個(gè)意外的結(jié)果那教程就等于失敗了婚瓜， 即使這不是你的鍋宝鼓。

當(dāng)你的學(xué)生和你在一起時(shí)你可以現(xiàn)場(chǎng)解決問(wèn)題；如果他們自己閱讀文檔你就不到這一點(diǎn)了巴刻。所以必須提前防止這種情況發(fā)生愚铡，emm，這說(shuō)起來(lái)容易做起來(lái)難。

確保用戶可以立刻得到結(jié)果

初學(xué)者所做的一切都應(yīng)該是容易理解的沥寥。如果他在看到結(jié)果之前必須做很多步難以理解的操作那就很糟糕了碍舍。每一個(gè)操作的效果都應(yīng)立即展示出來(lái)，并且明確它與操作之間的聯(lián)系邑雅。教程的每個(gè)部分或整個(gè)教程的結(jié)論必須是有意義的片橡。

確保你的教程可重復(fù)

教程必須能可靠地重復(fù)，這其實(shí)不容易實(shí)現(xiàn)淮野，因?yàn)槿藗兪褂貌煌牟僮飨到y(tǒng)捧书，經(jīng)驗(yàn)水平也不一樣。更不要說(shuō)他們使用的軟件或資源很可能在一段時(shí)間內(nèi)會(huì)發(fā)生變化骤星，比如版本经瓷。因此教程需要定期和詳細(xì)的測(cè)試，以確保它們一直有效洞难。

關(guān)注具體步驟而非抽象概念

教程需要具體舆吮，圍繞特定的操作和結(jié)果展開(kāi)。引入抽象的概念通常誘惑巨大队贱，但是所有的學(xué)習(xí)都是從特定和具體到一般和抽象色冀。

提供最低限度的必要說(shuō)明

不要解釋學(xué)習(xí)者完成教程不需要知道的任何內(nèi)容。擴(kuò)展討論很重要但它不是教程的作用露筒，在教程中這反而是一個(gè)會(huì)讓學(xué)習(xí)者分散注意力的絆腳石呐伞。只要有最低限度的解釋就可以了，你可以鏈接到文檔中其他地方的說(shuō)明慎式。

只關(guān)注用戶需要采取的步驟

教程只需要專注于學(xué)習(xí)者手頭的任務(wù)伶氢。也許你的命令有許多其他選項(xiàng)，或者可能有不同的方法來(lái)訪問(wèn)某個(gè) API瘪吏。但是現(xiàn)在你的學(xué)習(xí)者不需要了解那些就能取得進(jìn)步癣防。

操作指南

操作指南使讀者了解解決實(shí)際問(wèn)題所需的步驟。它們是食譜掌眠，實(shí)現(xiàn)特定的目標(biāo)蕾盯。例如如何創(chuàng)建Web表單，如何繪制三維數(shù)據(jù)集蓝丙，如何啟用 LDAP 身份驗(yàn)證级遭。

操作指南完全以目標(biāo)為導(dǎo)向。想想一個(gè)食譜就可以渺尘，它解決了一個(gè)具體問(wèn)題挫鸽，我們可以假設(shè)用戶已經(jīng)擁有一些基本知識(shí)，他僅僅想知道如何實(shí)現(xiàn)某些目標(biāo)鸥跟。操作指南與教程完全不同丢郊，操作指南是對(duì)初學(xué)者甚至無(wú)法提出的那些問(wèn)題進(jìn)行的回答盔沫。

在操作指南中我們可以假設(shè)用戶已經(jīng)知道如何執(zhí)行基本操作并使用基本的工具。讓我們開(kāi)心的是枫匾，不少軟件文檔中的操作指南往往做得都還不錯(cuò)架诞。

如何寫出好的操作指南

提供一系列步驟

操作指南必須包含需要按順序執(zhí)行的步驟列表（就像教程一樣）。你不必從頭開(kāi)始而是應(yīng)該找到一個(gè)合理的起點(diǎn)干茉。操作指南應(yīng)該可靠谴忧，但不需要具有教程那樣萬(wàn)無(wú)一失的可重復(fù)性。

關(guān)注結(jié)果

操作指南必須注重實(shí)現(xiàn)目標(biāo)等脂，其它的都會(huì)讓用戶分析俏蛮，與教程一樣，詳細(xì)的說(shuō)明在這里也不合適上遥。

解決問(wèn)題

操作指南必須解決特定的問(wèn)題搏屑，也就是「我如何...」。這是操作指南與教程不同的地方：當(dāng)涉及到操作指南時(shí)粉楚，可以假定讀者知道他們應(yīng)該實(shí)現(xiàn)什么但不知道如何實(shí)現(xiàn)辣恋， 而在教程中你有責(zé)任決定學(xué)習(xí)者需要了解的內(nèi)容。

不要解釋概念

操作指南不應(yīng)該進(jìn)行解釋模软，這里不是討論的地方伟骨，它們只會(huì)妨礙用戶操作。如果解釋很重要請(qǐng)鏈接到該有的地方燃异。

允許一些靈活性

操作指南應(yīng)該允許用稍微不同的方式來(lái)做同樣的事情携狭。它需要足夠的靈活性，用戶可以看到如何應(yīng)用于與你描述示例略有不同的場(chǎng)景回俐，或者了解如何使其適應(yīng)與你假設(shè)略有不同的系統(tǒng)或配置逛腿。

該結(jié)束就結(jié)束

實(shí)際的可操作性比完整更有價(jià)值。教程需要完整但是操作指南不需要仅颇。它們可以在合適的地方開(kāi)始和結(jié)束单默，也不需要提及所有和主題相關(guān)的內(nèi)容。臃腫的操作指南無(wú)法幫助用戶快速獲得解決方案忘瓦。

認(rèn)真命名標(biāo)題

操作方法文檔的標(biāo)題應(yīng)該告訴用戶確切的內(nèi)容并且指明是一個(gè)操作指南搁廓。比如「如何創(chuàng)建基于類的視圖」就是一個(gè)好的標(biāo)題，但是直接叫「基于類的視圖」就不好了耕皮。

參考

參考是工具的技術(shù)描述和如何進(jìn)行操作境蜕。

參考只有一個(gè)任務(wù)就是描述。它們是由代碼決定的凌停，因?yàn)槊枋龅氖牵宏P(guān)鍵類汽摹，函數(shù)，API等等苦锨，應(yīng)該列出函數(shù)，字段，屬性和方法等內(nèi)容并列出如何使用它們舟舒。

參考以信息為導(dǎo)向拉庶。技術(shù)參考可以包含示例來(lái)說(shuō)明用法但它不應(yīng)該嘗試解釋基本概念或者如何實(shí)現(xiàn)通用的功能。參考資料也應(yīng)該是切中要害的秃励。用烹飪類比氏仗，它可能是一篇關(guān)于某種食材的文章，描述了它的來(lái)源夺鲜、化學(xué)成分和如何烹飪等等皆尔。

請(qǐng)注意，描述確實(shí)包括了如何使用工具的基本描述币励，比如如何實(shí)例化特定類或調(diào)用某個(gè)方法慷蠕，或者在將某些東西傳遞給函數(shù)時(shí)必須采取的預(yù)防措施。然而這僅僅是其作為技術(shù)參考功能的一部分而且和操作指南也完全不同食呻。

對(duì)于一些開(kāi)發(fā)人員流炕，參考指南是他們可以想到的唯一文檔形式。他們已經(jīng)了解了自己的軟件并且知道如何使用它仅胞，所以他們想象其他人可能需要的就僅僅是它的技術(shù)信息每辟。參考往往很多軟件也寫得很好，現(xiàn)在它甚至可以在某種程度上自動(dòng)生成干旧。

如何編寫好的參考文檔

在代碼周圍構(gòu)建文檔

為參考文檔提供與代碼庫(kù)相同的結(jié)構(gòu)渠欺，以便用戶可以同時(shí)瀏覽代碼和文檔。這也將有助于維護(hù)人員查看缺少參考文檔或需要更新的位置椎眯。

始終如一

在參考指南中挠将，結(jié)構(gòu)，格式必須一致盅视，與百科全書或字典一致捐名。

只進(jìn)行描述

技術(shù)參考的唯一任務(wù)是盡可能清楚和完整地描述。其他任何事情（解釋闹击，討論镶蹋，指導(dǎo)，推測(cè)赏半，意見(jiàn)）不僅會(huì)分散注意力贺归，而且會(huì)使其更難以使用和維護(hù)。避免使用參考來(lái)指導(dǎo)如何實(shí)現(xiàn)某種功能断箫，并且不要對(duì)概念或討論進(jìn)行解釋拂酣。如果需要，可以酌情鏈接到操作指南說(shuō)明和入門教程中仲义。

準(zhǔn)確

這些描述必須準(zhǔn)確并保持最新?tīng)顟B(tài)婶熬。工具與描述之間的任何差異都將不可避免地導(dǎo)致用戶誤入歧途剑勾。

說(shuō)明

說(shuō)明用來(lái)解釋、討論和闡明特定的一個(gè)主題赵颅，它們拓寬了文檔對(duì)某一主題的覆蓋范圍虽另。說(shuō)明是以理解為導(dǎo)向的。解釋同樣可以描述為討論饺谬。它可以讓你從更廣泛的視角捂刺，從更高層次甚至從不同角度闡明它∧颊可以想象一個(gè)討論文檔是在閑暇時(shí)閱讀的族展，而不是在瀏覽代碼時(shí)閱讀。

通常這部分文檔很少被明確的創(chuàng)建拔鹰，解釋的片段會(huì)分散在其他部分中仪缸。其實(shí)說(shuō)明和討論不像看起來(lái)那么容易創(chuàng)建 ，它的主題不是由你想要實(shí)現(xiàn)的特定任務(wù)定義的（操作指南）格郁，也不是你希望用戶學(xué)習(xí)的（教程）腹殿，當(dāng)然也不是具體的函數(shù)定義的（參考材料）。

如何寫出好的說(shuō)明

提供上下文

說(shuō)明通常需要指明背景和上下文例书，有時(shí)候說(shuō)明還可以解釋「為什么是這樣」锣尉，可能是設(shè)計(jì)決策，歷史原因或者技術(shù)限制决采。

討論替代方案和意見(jiàn)

說(shuō)明也可以提供一些替代方案或同一問(wèn)題的多種不同方法自沧，甚至可以考慮并權(quán)衡相反的意見(jiàn)。

勿提供技術(shù)參考或指導(dǎo)

說(shuō)明應(yīng)該做的事情就是文檔其他部分沒(méi)有的東西树瞭。告知用戶如何做某事并不是說(shuō)明的任務(wù)它也不應(yīng)該提供技術(shù)描述拇厢，文檔的這些功能在其他部分中已經(jīng)完成了。

關(guān)于文檔結(jié)構(gòu)

為什么分界不明顯晒喷？

上文討論的文檔結(jié)構(gòu)很清楚并且很有效孝偎，但通常分界沒(méi)有那么明顯，這是因?yàn)槲臋n四象限中每個(gè)象限與相鄰的都會(huì)有一些重疊特征凉敲。

教程和操作指南是相似的衣盾，因?yàn)樗鼈兌缄P(guān)注描述實(shí)際步驟；操作指南與技術(shù)參考的交集在于它們是在實(shí)際工作和編碼時(shí)所需要的爷抓；參考指南和說(shuō)明相似是因?yàn)樗鼈冴P(guān)注理論知識(shí)势决；最后教程與說(shuō)明的共同點(diǎn)是它們?cè)谖覀冞M(jìn)行學(xué)習(xí)時(shí)最有用。如下表所示：

鑒于這些重疊蓝撇，不同類型的文檔變得混淆并相互混合也就不足為奇了果复。雖然很難找到完全使用這四種結(jié)構(gòu)的示例，但是大量的文檔都在努力以不同的方式來(lái)完成這四個(gè)類別的任務(wù)渤昌。有些項(xiàng)目就完全采用了這種結(jié)構(gòu)虽抄，包括Django（雖然在早期版本中沒(méi)有明確說(shuō)明）和django CMS走搁。這兩個(gè)項(xiàng)目中都證明了這種結(jié)構(gòu)的價(jià)值。

為什么要如此分析

本文的文檔結(jié)構(gòu)分析基于我多年編寫和維護(hù)文檔的經(jīng)驗(yàn)并花了很多時(shí)間考慮如何改進(jìn)它迈窟。它還基于各種學(xué)科的合理整合朱盐，例如，教程概念具有教學(xué)基礎(chǔ)菠隆；而且它假定存在一個(gè)老師和一個(gè)學(xué)習(xí)者，并把使用軟件作為一種「手藝」來(lái)看待狂秘。

使你的文檔更有用

文檔維護(hù)人員必須解決的最大問(wèn)題是沒(méi)有清楚了解他們應(yīng)該做什么骇径，以至于他們改了又改但發(fā)現(xiàn)還是很難令人滿意。本文討論的文檔結(jié)構(gòu)通過(guò)明確的分工來(lái)解決這些問(wèn)題者春，基于此制作的文檔也更易于編寫和維護(hù)破衔，同時(shí)也更易于使用。

應(yīng)該寫什么钱烟，怎么寫晰筛，以及把它放在哪里都變得更加清晰。

總的來(lái)說(shuō)拴袭，針對(duì)四象限中的每一個(gè)文檔進(jìn)行明確的編寫有助于軟件吸引和留住更多用戶同時(shí)用戶可以更高效地使用读第，這是軟件開(kāi)發(fā)者最想要的東西之一。