如何撰寫技術文件

ValueMar發表於2018-11-18
原文來自 What nobody tells you about documentation，本文是本人整理翻譯而成。
關於如何寫好一個完善的軟體文件，這裡應當是有四要素，而不是一個。它們分別是：教程，操作指南，說明和技術參考。它們代表四種不同的目的和功能，並且需要四種不同的方法來建立它們。瞭解這一點的含義有助於改進大多數的軟體文件-通常會有非常好的效果。

前言

軟體有多好並不重要，因為如果文件不夠好，人們就不會使用它。
即使由於某種原因他們不得不使用它，這是因為他們沒有選擇，沒有良好的文件，他們將不會有效地使用它或者你喜歡它的方式。幾乎每個人都明白這一點。 幾乎每個人都知道他們需要良好的文件，並且大多數人都試圖建立好的文件。但大多數人都失敗了。通常這不是因為他們不夠努力，而是因為他們沒有找到正確的方式。
在本文中，我將解釋如何使您的文件更好，而不是通過更加努力，而是通過正確的方式。 正確的方法是更簡單的方法 – 更容易編寫，更容易維護。
有一些非常簡單的原則可以管理少見的有拼寫的文件。 它們似乎是一個祕密，儘管它們不應該是。如果您能夠將這些原則付諸實踐，它將使您的文件更好，您的專案，產品或團隊更成功 – 這是一個承諾。
文件需要包含並圍繞其四個不同的功能進行構建：教程，操作指南，說明和技術參考。 他們每個都需要一種獨特的寫作模式。 使用軟體的人在不同的環境中需要這四種不同的文件 – 因此軟體中通常都需要它們。並且需要圍繞它們明確地構建文件，並且它們必須保持獨立且彼此不同。
教程
操作指南
說明
技術參考
以學習為導向
以目標為導向
以理解為導向
以資訊為導向
允許新人入門
展示瞭如何解決特定問題
解釋
描述軟體
是一個課程
是一系列步驟
提供背景和上下文
是準確且完整的
這種劃分使作者和讀者明白了哪些資訊在哪裡。 它告訴作者如何編寫，編寫什麼以及在何處編寫它。 它使作者免於浪費大量時間來嘗試將他們想要傳達的資訊篡改成有意義的形狀，因為這些文件中的每一種只有一個工作。
事實上，維護良好的文件非常難以隱含或明確地識別該方案的象限。 每種型別的要求都與其他要求不同，因此任何未能保持這種結構的文件嘗試都會受到影響，因為它會立即被拉向不同的方向。
一旦理解了結構，它就成為一種非常有用的工具，用於分析現有文件，並瞭解需要採取哪些措施來改進它。
關於專案檔案您可能會問：更改日誌，貢獻策略以及有關專案的其他資訊在哪些方面適合此方案？ 答案是他們沒有 – 因為嚴格來說，他們是專案文件，而不是軟體本身的文件，
它們可以簡單地與其他材料一起儲存在適當命名的部分中 – 只要它們沒有混合在一起。
考慮到這一點，讓我們探討四個關鍵功能中的每一個。

教程

教程是讓讀者通過一系列步驟來完成某種專案的課程。 它們是您的專案所需要的，以向初學者展示他們可以用它實現某些目標。
他們完全以學習為導向，具體而言，他們的目標是學習如何而不是學習。
你是老師，你負責學生的工作。 在您的指導下，學生將執行一系列操作以達到目的。
結束和行動取決於你，但決定他們應該做什麼可能是艱苦的工作。 最終必須有意義，但對於一個完整的初學者也是可以實現的。
考慮一個教孩子做飯的比喻。
你教孩子做飯的內容並不重要。 重要的是，孩子覺得它很有樂趣，並且有信心，並希望再次這樣做。
通過孩子所做的事情，它將學習烹飪的重要事項。 它將瞭解在廚房裡使用餐具來處理食物是什麼感覺。
這是因為使用像烹飪這樣的軟體是一個技巧問題。 它是知識 – 但它是實踐知識，而不是理論知識。 當我們學習新工藝或技能時，我們總是開始學習它。
重要的是，完成教程後，學習者就能夠理解其餘的文件和軟體本身。
大多數軟體專案都有非常糟糕或不存在的教程。 教程將使您的學習者變成使用者。 錯誤或缺少的教程將阻止您的專案獲取新使用者。
好的教程很難寫。 它們需要對初學者有用，易於遵循，有意義且極其健壯。

允許使用者學習

一開始，我們只是通過做才學到任何東西 – 這就是我們學會說話或走路的方式。
在您的軟體教程中，您的學習者需要做的事情。 在學習本教程時，他們所做的不同事情需要涵蓋廣泛的工具和操作，從最簡單的工具和操作開始，再到更復雜的工具和操作。

讓使用者開始

如果你的初學者的第一步是手持嬰兒步驟，這是完全可以接受的。 如果初學者要做的不是有經驗的人的方式，或者即使它不是“正確的”方式，那也是完全可以接受的 – 初學者的教程與最佳實踐的手冊不同。
教程的目的是讓學習者開始他們的旅程，而不是讓他們到達最終目的地。

請確認您的教程工作

作為導師，你的一個工作就是激發初學者的信心：在軟體，教程，導師中，當然，還有他們自己實現所要求的能力。
有很多事情可以促成這一點。 友好的語氣和語言的一致使用以及材料的邏輯進展都有所幫助。 但最重要的是，你要求初學者做的事必須奏效。 學習者需要看到你要求他們採取的行動會產生你說他們會有的效果。
如果學習者的動作產生錯誤或意外結果，那麼您的教程就會失敗 – 即使這不是您的錯。 當你的學生和你在一起時，你可以拯救他們;
如果他們自己閱讀你的文件你就不能 – 所以你必須提前防止這種情況發生。 毫無疑問，這說起來容易做起來難。

確保使用者立即獲得結果

學習者所做的一切都應該是可以理解的，無論多麼小。 如果你的學生在看到結果之前必須做兩頁的奇怪和難以理解的事情，那就太長了。 每一個行動的效果應儘快顯現和明顯，並且應明確與行動的聯絡。
教程的每個部分或整個教程的結論必須是有意義的成就。

使教程可重複

您的教程必須可靠地重複。 這不容易實現：人們將使用不同的作業系統，經驗和工具水平來實現它。 更重要的是，他們使用的任何軟體或資源很可能在此期間發生變化。
每次教程都必須適用於所有這些教程。
不幸的是，教程需要定期和詳細的測試，以確保它們仍然有效。

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

教程需要具體，圍繞特定的，特定的行動和結果。
引入抽象的誘惑是巨大的;
畢竟大多數計算是如何獲得它的力量的。但是所有的學習都是從特定的，具體的到一般的和抽象的，並且要求學習者在他們甚至有機會掌握具體內容之前欣賞抽象層次是教學不好。

提供最低限度的必要解釋

不要解釋學習者為了完成教程而不需要知道的任何內容。擴充套件討論很重要 – 只是不在教程中。在教程中，這是一個障礙和分心。只有最低限度是合適的。相反，請連結到文件中其他地方的解釋。

只關注使用者需要採取的步驟

您的教程需要專注於手頭的任務。也許您引入的命令有許多其他選項，或者可能有不同的方法來訪問某個API。沒關係：現在，你的學習者不需要了解那些才能取得進步。

操作指南

操作指南使讀者瞭解解決實際問題所需的步驟。
它們是食譜，實現特定目標的方向 – 例如：如何建立Web表單;
如何繪製三維資料集;
如何啟用LDAP身份驗證。
他們完全以目標為導向。
如果你想要一個比喻，想想一個食譜，準備吃東西。
配方有明確的定義結束。 它解決了一個具體問題。 它表明某人 – 可以假設他已經擁有一些基本知識 – 如何實現某些目標。
操作指南與教程完全不同。 操作指南是對真正的初學者甚至無法制定的問題的回答。
在操作指南中，您可以假設一些知識和理解。 您可以假設使用者已經知道如何執行基本操作並使用基本工具。

提供一系列步驟

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

關注結果

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

解決問題

操作指南必須解決特定的問題或問題：我如何…？
這是操作指南與教程不同的一種方式：當涉及到操作指南時，可以假定讀者知道他們應該實現什麼，但還不知道如何 – 而在本教程中，您有責任決定讀者需要了解的內容。

不要解釋概念

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

允許一些靈活性

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

隨時離開

實際可用性比完整性更有價值。教程需要完整，端到端的指南;
操作指南沒有。它們可以在適合您的地方開始和結束。他們不需要提及所有要提及的內容，只是因為它與主題相關。臃腫的操作指南無法幫助使用者快速獲得解決方案。

標題對使用者友好

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

技術參考

技術參考是機器的技術說明以及如何操作。
技術參考只有一個工作：描述。它們是由程式碼決定的，因為它們最終描述的是：關鍵類，函式，API等等，它們應該列出函式，欄位，屬性和方法等內容，並列出如何使用它們。
參考資料是面向資訊的。
通過各種方式技術參考可以包含示例來說明用法，但它不應該嘗試解釋基本概念，或者如何實現共同任務。
參考資料應該是嚴格的，切中要害的。
烹飪類比可能是一篇關於一種成分的環球文章，描述了它的來源，它的行為，它的化學成分，它是如何烹飪的。
請注意，描述確實包括如何使用機器的基本描述 – 如何例項化特定類，或呼叫某個方法，或者在將某些東西傳遞給函式時必須採取的預防措施。然而，這僅僅是其作為技術參考的功能的一部分，並且強調不要與操作指南相混淆 – 描述軟體的正確使用（技術參考）與顯示如何使用它來實現某一目的不同（方法文件）。
對於一些開發人員，參考指南是他們可以想象的唯一文件。他們已經瞭解他們的軟體，他們知道如何使用它。他們可以想象其他人可能需要的是關於它的技術資訊。
參考材料往往寫得很好。它甚至可以在某種程度上自動生成，但這本身就不夠了。

構建程式碼周圍的文件

為參考文件提供與程式碼庫相同的結構，以便使用者可以同時導航程式碼和文件。這也將有助於維護人員檢視缺少參考文件或需要更新的位置。

始終如一

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

不要做任何描述

技術參考的唯一工作是儘可能清楚和完整地描述。其他任何事情（解釋，討論，指導，推測，意見）不僅會分散注意力，而且會使其更難以使用和維護。提供示例以在適當時說明說明。
避免使用參考材料來指導如何實現事物，超出使用軟體的基本範圍，並且不允許對主題的概念或討論進行解釋。相反，請酌情連結到操作指南，說明和教程。

準確性

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

說明

說明或討論，闡明和闡明特定主題。它們拓寬了文件對主題的覆蓋範圍。
他們是理解導向的。
說明同樣可以描述為討論。它們是文件放鬆和退回軟體的機會，從更廣泛的視角，從更高層次甚至從不同角度闡明它。您可以想象一個討論文件是在閒暇時閱讀，而不是在程式碼上閱讀。
這部分文件很少明確建立，相反，解釋的片段分散在其他部分中。有時，該部分存在，但有一個名稱，如背景或其他筆記，並沒有真正公正的功能。
討論不像看起來那麼容易建立 – 當你有一個問題的起點時，直接解釋的東西就不那麼容易了，當你有一個空白頁面並且必須寫下一些關於它的東西時。
主題不是由您想要實現的特定任務定義的，例如操作指南，或者您希望使用者學習的內容，例如教程。它不是由一塊機器定義的，比如參考材料。它是由您認為一次嘗試覆蓋的合理區域定義的，因此討論主題的劃分有時可能有點武斷。

提供上下文

說明是背景和上下文的位置 – 例如，Web表單以及如何在Django或Search和django CMS中處理它們。
他們還可以說明為什麼事情如此 – 設計決策，歷史原因，技術限制。

討論替代方案和意見

說明可以考慮替代方案，或同一問題的多種不同方法。例如，在關於Django部署的文章中，考慮和評估不同的Web伺服器選項是合適的，
討論甚至可以考慮並權衡相反的意見 – 例如，測試模組是否應該在包目錄中。

請勿指導或提供技術參考

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

來源：https://juejin.im/post/5bf0f164518825305520fc59#comment

相關文章