「譯」如何撰寫技術文檔

原文來自 What nobody tells you about documentation，本文是本人整理翻譯而成。

關於如何寫好一個完善的軟件文檔，這裏應當是有四要素，而不是一個。它們分別是：教程，操做指南，說明和技術參考。它們表明四種不一樣的目的和功能，而且須要四種不一樣的方法來建立它們。瞭解這一點的含義有助於改進大多數的軟件文檔-一般會有很是好的效果。

前言

軟件有多好並不重要，由於若是文檔不夠好，人們就不會使用它。

即便因爲某種緣由他們不得不使用它，這是由於他們沒有選擇，沒有良好的文檔，他們將不會有效地使用它或者你喜歡它的方式。幾乎每一個人都明白這一點。 幾乎每一個人都知道他們須要良好的文檔，而且大多數人都試圖建立好的文檔。但大多數人都失敗了。一般這不是由於他們不夠努力，而是由於他們沒有找到正確的方式。

在本文中，我將解釋如何使您的文檔更好，而不是經過更加努力，而是經過正確的方式。 正確的方法是更簡單的方法 - 更容易編寫，更容易維護。

有一些很是簡單的原則能夠管理少見的有拼寫的文檔。 它們彷佛是一個祕密，儘管它們不該該是。若是您可以將這些原則付諸實踐，它將使您的文檔更好，您的項目，產品或團隊更成功 - 這是一個承諾。

文檔須要包含並圍繞其四個不一樣的功能進行構建：教程，操做指南，說明和技術參考。 他們每一個都須要一種獨特的寫做模式。 使用軟件的人在不一樣的環境中須要這四種不一樣的文檔 - 所以軟件中一般都須要它們。而且須要圍繞它們明確地構建文檔，而且它們必須保持獨立且彼此不一樣。

教程	操做指南	說明	技術參考
以學習爲導向	以目標爲導向	以理解爲導向	以信息爲導向
容許新人入門	展現瞭如何解決特定問題	解釋	描述軟件
是一個課程	是一系列步驟	提供背景和上下文	是準確且完整的

這種劃分使做者和讀者明白了哪些信息在哪裏。 它告訴做者如何編寫，編寫什麼以及在何處編寫它。 它使做者免於浪費大量時間來嘗試將他們想要傳達的信息篡改爲有意義的形狀，由於這些文檔中的每一種只有一個工做。

事實上，維護良好的文檔很是難以隱含或明確地識別該方案的象限。 每種類型的要求都與其餘要求不一樣，所以任何未能保持這種結構的文檔嘗試都會受到影響，由於它會當即被拉向不一樣的方向。

一旦理解告終構，它就成爲一種很是有用的工具，用於分析現有文檔，並瞭解須要採起哪些措施來改進它。

關於項目文件您可能會問：更改日誌，貢獻策略以及有關項目的其餘信息在哪些方面適合此方案？ 答案是他們沒有 - 由於嚴格來講，他們是項目文檔，而不是軟件自己的文檔，

它們能夠簡單地與其餘材料一塊兒保存在適當命名的部分中 - 只要它們沒有混合在一塊兒。

考慮到這一點，讓咱們探討四個關鍵功能中的每個。

教程

教程是讓讀者經過一系列步驟來完成某種項目的課程。 它們是您的項目所須要的，以向初學者展現他們能夠用它實現某些目標。

他們徹底以學習爲導向，具體而言，他們的目標是學習如何而不是學習。

你是老師，你負責學生的工做。 在您的指導下，學生將執行一系列操做以達到目的。

結束和行動取決於你，但決定他們應該作什麼多是艱苦的工做。 最終必須有意義，但對於一個完整的初學者也是能夠實現的。

考慮一個教孩子作飯的比喻。

你教孩子作飯的內容並不重要。 重要的是，孩子以爲它頗有樂趣，而且有信心，並但願再次這樣作。

經過孩子所作的事情，它將學習烹飪的重要事項。 它將瞭解在廚房裏使用餐具來處理食物是什麼感受。

這是由於使用像烹飪這樣的軟件是一個技巧問題。 它是知識 - 但它是實踐知識，而不是理論知識。 當咱們學習新工藝或技能時，咱們老是開始學習它。

重要的是，完成教程後，學習者就可以理解其他的文檔和軟件自己。

大多數軟件項目都有很是糟糕或不存在的教程。 教程將使您的學習者變成用戶。 錯誤或缺乏的教程將阻止您的項目獲取新用戶。

好的教程很難寫。 它們須要對初學者有用，易於遵循，有意義且極其健壯。

容許用戶學習

一開始，咱們只是經過作才學到任何東西 - 這就是咱們學會說話或走路的方式。

在您的軟件教程中，您的學習者須要作的事情。 在學習本教程時，他們所作的不一樣事情須要涵蓋普遍的工具和操做，從最簡單的工具和操做開始，再到更復雜的工具和操做。

讓用戶開始

若是你的初學者的第一步是手持嬰兒步驟，這是徹底能夠接受的。 若是初學者要作的不是有經驗的人的方式，或者即便它不是「正確的」方式，那也是徹底能夠接受的 - 初學者的教程與最佳實踐的手冊不一樣。

教程的目的是讓學習者開始他們的旅程，而不是讓他們到達最終目的地。

請確認您的教程工做

做爲導師，你的一個工做就是激發初學者的信心：在軟件，教程，導師中，固然，還有他們本身實現所要求的能力。

有不少事情能夠促成這一點。 友好的語氣和語言的一導致用以及材料的邏輯進展都有所幫助。 但最重要的是，你要求初學者作的事必須奏效。 學習者須要看到你要求他們採起的行動會產生你說他們會有的效果。

若是學習者的動做產生錯誤或意外結果，那麼您的教程就會失敗 - 即便這不是您的錯。 當你的學生和你在一塊兒時，你能夠拯救他們; 若是他們本身閱讀你的文檔你就不能 - 因此你必須提早防止這種狀況發生。 毫無疑問，這提及來容易作起來難。

確保用戶當即得到結果

學習者所作的一切都應該是能夠理解的，不管多麼小。 若是你的學生在看到結果以前必須作兩頁的奇怪和難以理解的事情，那就太長了。 每個行動的效果應儘快顯現和明顯，而且應明確與行動的聯繫。

教程的每一個部分或整個教程的結論必須是有意義的成就。

使教程可重複

您的教程必須可靠地重複。 這不容易實現：人們將使用不一樣的操做系統，經驗和工具水平來實現它。 更重要的是，他們使用的任何軟件或資源極可能在此期間發生變化。

每次教程都必須適用於全部這些教程。

不幸的是，教程須要按期和詳細的測試，以確保它們仍然有效。

關注具體步驟，而非抽象概念

教程須要具體，圍繞特定的，特定的行動和結果。

引入抽象的誘惑是巨大的;畢竟大多數計算是如何得到它的力量的。可是全部的學習都是從特定的，具體的到通常的和抽象的，而且要求學習者在他們甚至有機會掌握具體內容以前欣賞抽象層次是教學很差。

提供最低限度的必要解釋

不要解釋學習者爲了完成教程而不須要知道的任何內容。擴展討論很重要 - 只是不在教程中。在教程中，這是一個障礙和分心。只有最低限度是合適的。相反，請連接到文檔中其餘地方的解釋。

只關注用戶須要採起的步驟

您的教程須要專一於手頭的任務。也許您引入的命令有許多其餘選項，或者可能有不一樣的方法來訪問某個API。不要緊：如今，你的學習者不須要了解那些才能取得進步。

操做指南

操做指南使讀者瞭解解決實際問題所需的步驟。

它們是食譜，實現特定目標的方向 - 例如：如何建立Web表單; 如何繪製三維數據集; 如何啓用LDAP身份驗證。

他們徹底以目標爲導向。

若是你想要一個比喻，想一想一個食譜，準備吃東西。

配方有明確的定義結束。 它解決了一個具體問題。 它代表某人 - 能夠假設他已經擁有一些基本知識 - 如何實現某些目標。

操做指南與教程徹底不一樣。 操做指南是對真正的初學者甚至沒法制定的問題的回答。

在操做指南中，您能夠假設一些知識和理解。 您能夠假設用戶已經知道如何執行基本操做並使用基本工具。

提供一系列步驟

操做指南必須包含須要按順序執行的步驟列表（就像教程同樣）。你沒必要從一開始就開始，只是在一個合理的起點。操做指南應該可靠，但它們不須要具備教程的鑄鐵可重複性。

關注結果

操做指南必須注重實現實際目標。別的什麼都是分心。與教程同樣，詳細說明在這裏不合適。

解決問題

操做指南必須解決特定的問題或問題：我如何...？

這是操做指南與教程不一樣的一種方式：當涉及到操做指南時，能夠假定讀者知道他們應該實現什麼，但還不知道如何 - 而在本教程中，您有責任決定讀者須要瞭解的內容。

不要解釋概念

操做指南不該該解釋事情。這不是那種討論的地方;他們只會妨礙行動。若是解釋很重要，請連接到它們。

容許一些靈活性

操做指南應該容許稍微不一樣的方式來作一樣的事情。它須要足夠的靈活性，用戶能夠看到它將如何應用於與您描述的示例略有不一樣的示例，或者瞭解如何使其適應與您假設的略有不一樣的系統或配置。除非你想到的確切目的，不然不要那麼具體，指南對任何事情都沒用。

隨時離開

實際可用性比完整性更有價值。教程須要完整，端到端的指南;操做指南沒有。它們能夠在適合您的地方開始和結束。他們不須要說起全部要說起的內容，只是由於它與主題相關。臃腫的操做指南沒法幫助用戶快速得到解決方案。

標題對用戶友好

操做方法文檔的標題應該告訴用戶確切的內容。如何建立基於類的視圖是一個很好的標題。建立基於類的視圖或更糟糕的是，基於類的視圖不是。

技術參考

技術參考是機器的技術說明以及如何操做。

技術參考只有一個工做：描述。它們是由代碼決定的，由於它們最終描述的是：關鍵類，函數，API等等，它們應該列出函數，字段，屬性和方法等內容，並列出如何使用它們。

參考資料是面向信息的。

經過各類方式技術參考能夠包含示例來講明用法，但它不該該嘗試解釋基本概念，或者如何實現共同任務。

參考資料應該是嚴格的，切中要害的。

烹飪類比多是一篇關於一種成分的環球文章，描述了它的來源，它的行爲，它的化學成分，它是如何烹飪的。

請注意，描述確實包括如何使用機器的基本描述 - 如何實例化特定類，或調用某個方法，或者在將某些東西傳遞給函數時必須採起的預防措施。然而，這僅僅是其做爲技術參考的功能的一部分，而且強調不要與操做指南相混淆 - 描述軟件的正確使用（技術參考）與顯示如何使用它來實現某一目的不一樣（方法文檔）。

對於一些開發人員，參考指南是他們能夠想象的惟一文檔。他們已經瞭解他們的軟件，他們知道如何使用它。他們能夠想象其餘人可能須要的是關於它的技術信息。

參考材料每每寫得很好。它甚至能夠在某種程度上自動生成，但這自己就不夠了。

構建代碼周圍的文檔

爲參考文檔提供與代碼庫相同的結構，以便用戶能夠同時導航代碼和文檔。這也將有助於維護人員查看缺乏參考文檔或須要更新的位置。

始終如一

在技術參考中，結構，音調，格式必須一致 - 與百科全書或字典一致。

不要作任何描述

技術參考的惟一工做是儘量清楚和完整地描述。其餘任何事情（解釋，討論，指導，推測，意見）不只會分散注意力，並且會使其更難以使用和維護。提供示例以在適當時說明說明。

避免使用參考材料來指導如何實現事物，超出使用軟件的基本範圍，而且不容許對主題的概念或討論進行解釋。相反，請酌情連接到操做指南，說明和教程。

準確性

這些描述必須準確並保持最新狀態。機器與您對它的描述之間的任何差別都將不可避免地致使用戶誤入歧途。

說明

說明或討論，闡明和闡明特定主題。它們拓寬了文檔對主題的覆蓋範圍。

他們是理解導向的。

說明一樣能夠描述爲討論。它們是文檔放鬆和退回軟件的機會，從更普遍的視角，從更高層次甚至從不一樣角度闡明它。您能夠想象一個討論文檔是在閒暇時閱讀，而不是在代碼上閱讀。

這部分文檔不多明確建立，相反，解釋的片斷分散在其餘部分中。有時，該部分存在，但有一個名稱，如背景或其餘筆記，並無真正公正的功能。

討論不像看起來那麼容易建立 - 當你有一個問題的起點時，直接解釋的東西就不那麼容易了，當你有一個空白頁面而且必須寫下一些關於它的東西時。

主題不是由您想要實現的特定任務定義的，例如操做指南，或者您但願用戶學習的內容，例如教程。它不是由一塊機器定義的，好比參考材料。它是由您認爲一次嘗試覆蓋的合理區域定義的，所以討論主題的劃分有時可能有點武斷。

提供上下文

說明是背景和上下文的位置 - 例如，Web表單以及如何在Django或Search和django CMS中處理它們。

他們還能夠說明爲何事情如此 - 設計決策，歷史緣由，技術限制。

討論替代方案和意見

說明能夠考慮替代方案，或同一問題的多種不一樣方法。例如，在關於Django部署的文章中，考慮和評估不一樣的Web服務器選項是合適的，

討論甚至能夠考慮並權衡相反的意見 - 例如，測試模塊是否應該在包目錄中。

請勿指導或提供技術參考

說明應該作的事情是文檔的其餘部分沒有的。指示用戶如何作某事並非解釋的地方。它也不該該提供技術描述。文檔的這些功能已在其餘部分中處理。