編寫第一個軟件文檔的指南

作為開發人員，您的驕傲和喜悅是您的代碼。它是可讀的，符合乾燥原則，反映了最佳實踐，最終產品是一個很好的工具，可以解決其目標用戶的某種問題。但是，無論您在代碼中投入了多少工作，如果您的軟件沒有文檔，或者您將文檔作為事後思考，並且對其進行了很少的重視處理，那麼用戶可能會很少能找到使用它的樂趣，並且最終選擇了不同的，更易於用戶友好的產品。

>在本文中，您會發現許多實用的指導原則，可以通過編寫第一個軟件文檔來啟動並運行。

鑰匙要點

• 好的軟件文檔對於用戶採用和理解至關重要，它是開發人員和用戶之間的通信工具。它應包括教程，操作指南，參考指南和說明，為軟件功能提供全面的指南。
>
• 應清楚地識別用於文檔的目標受眾，因為這將塑造所使用的內容和語言。在本指南的背景下，重點是針對對軟件熟悉的開發人員的文檔，而不是用戶手冊或項目文檔。
• >文檔應易於發現，結構良好並定期更新。建議將文檔保持在源控制中，以確保在發生代碼更新時保持相關和準確。包括常見問題解答頁面還可以幫助解決常見的用戶查詢。
• 除了傳統文檔之外，博客文章可以用作解釋軟件功能，提供教程和共享更新的有用工具。這可以培養圍繞軟件的社區，從而有助於其增長和成功。良好的文檔實踐的示例可以在諸如Greensock，React和Vue.js.
等平台中找到。

為什麼文檔很重要

>

參考您的軟件，Mike Pope有一個合適的說法：如果沒有記錄，則不存在。

為什麼？ 好吧，只是以我的個人經驗為例，我正在瀏覽網絡，以尋找新的JavaScript動畫庫來嘗試，我遇到了一個我真正喜歡的功能的描述。但是，沒有文檔，甚至沒有入門部分，而只是一個裸露的API頁面，幾乎沒有解釋或示例。您認為我最終使用了該庫嗎？當然，我沒有。我對此感到非常沮喪，以至於我繼續對自己更有意義的事情。

>

的問題為什麼好的javascript庫失敗，nicholos zakas給出了以下答案：

缺乏文檔。無論您的圖書館多麼美妙以及它的設計多麼聰明，如果您是唯一了解它的人，它都不會有任何好處。文檔不僅意味著自動化的API參考，還意味著註釋的示例和深入的教程。您需要所有這三個，以確保您的庫可以輕鬆地採用。

>您的軟件文檔至關重要的另一個重要原因是它們是您當前的自我和未來自我之間以及當前自我與其他開發人員之間的交流工具，這些工具最終可能會發現自己從事您的軟件。即使您編寫可讀和評論的代碼，這並不一定意味著您仍然會在六個月的時間內清楚您為什麼寫函數或以此為代碼的任何其他代碼。

>文檔允許您在代碼背後傳輸為什麼。以相同的方式，代碼註釋解釋了為什麼，而不是>>，文檔的目的相同。 - 撰寫文檔的初學者指南>

>當然，您希望人們使用您的代碼，並最終能夠對其進行更新並改進它。這些都是為您的產品背後的支持社區增長的重要因素，這對於獲得穩健性，成熟度和成功很重要。

> 如果您的軟件沒有很好的文檔可以使用。

誰軟件文檔適用於

>

撰寫任何內容時，請確保您的聽眾是誰。文檔也不例外。這樣做會闡明您的觀眾可能面臨的問題，這可能對您的產品或使用產品的先決條件。此信息對於您創建內容和使用的語言的方式至關重要。

>

有兩種文檔本文不關心：

>

1. >用戶手冊。例如，我姐姐可能決定使用WordPress發布自己的博客。她不是開發人員，但聽說非Devs可以隨時與WordPress一起啟動並運行他們的博客。現在，她將需要有關如何在服務器上下載和配置軟件的說明手冊。
2. >項目文檔。這種文檔與項目本身的關係更多，儘管它的某些內容可能會在項目的README文件中進行。為了繼續進行WordPress示例，在使用WordPress進行了大量練習之後，我可能會決定要在軟件中添加功能或修復一個或兩個錯誤。在這種情況下，我需要了解諸如變更，慣例和最佳實踐，貢獻政策，如何參與與手頭任務相關的團隊討論等的事情等。

>我在這裡想到的文檔類型主要是針對對您的軟件熟悉並且需要在項目中使用它的開發人員。例如，如果我要創建一個WordPress主題，那麼我需要知道如何開始，如何包括樣式表和JavaScript文檔，如何與數據庫進行通信以顯示帖子等。

在您的文檔中包含什麼

>一種流行的方法是由湯姆·普雷斯頓·妻子（Tom Preston-Werner）倡導的README驅動開發。它包括在開始編寫任何代碼之前編寫readme文檔。該文檔是對您軟件的介紹，通常包括：

>

>對您的軟件的功能以及它解決的問題的解釋

>
• 一個示例說明通常使用代碼的情況
>
• >鏈接到代碼和錯誤跟踪器
• 常見問題解答和尋求支持的方法
• >有關如何安裝軟件的說明
• >許可信息
• 但是，在我看來，擁有一個可靠的文檔，可以真正幫助使用您的軟件/庫的開發人員遠遠超出經典的讀數文件。在Daniele Procida之後，我建議您在文檔材料中包括以下項目以獲得出色的用戶體驗。
>教程

初學者會喜歡在您的軟件文檔中找到一個教程。教程旨在向用戶展示如何使用您的軟件完成項目，以便他們可以快速了解自己可以做的事情。

>

>教程是

課程

，可以將讀者藉助一系列步驟完成某種項目。它們是您的項目所需的，以便向初學者展示他們可以通過它實現的目標。 -

daniele procida

操作方法指南

操作方法指南可幫助用戶使用軟件解決現實世界任務。 Procida將它們與食譜進行了比較，因為它們是您給用戶提供的方向，以便他們可以成功實現某個目標。與針對完整初學者的教程不同，如何指導用戶已經擁有一些對功能，工具以及如何執行簡單任務的基本知識。

參考指南

參考指南是您軟件代碼的技術參考 - 功能，API等 - 並提供有關如何使用軟件的基本描述。例如，您會找到一個說明，說明如何實例化特定類，如何調用特定方法等等。

參考指南是機械的技術描述，以及如何操作它。 -

daniele procida

>這是您在大多數項目中可能會找到的文檔。開發人員傾向於編寫它，因為他們對自己的代碼了解全部了解。 >說明

的解釋是您認為與您對軟件的高層理解有關的特定主題的深入研究或討論。關於解釋，Procida指出 -

這部分文檔很少是明確創建的，而是在其他部分中分散了解釋的片段。有時，該部分存在，但有一個名稱，例如

>背景或其他註釋

，並且並不能真正對該功能公正。

>

>主題不是由您要完成的特定任務（例如如何指南）或您希望用戶學習的內容（例如教程）來定義的。它不是由參考材料而定義的。它的定義是由您認為是一個合理的領域，以便

>>>>

一次，因此討論的主題有時可能是任意的。 >

您需要注意的事情

> >讓我們瀏覽一些有用的指針，以使您的文檔用戶友好且相關。 使您的文檔可發現

>

>最好讓您易於找到軟件文檔。您可以將某些SEO技術與某些營銷策略一起使用，以便盡可能多的用戶可以掌握它。

>

>此外，您將文檔放入的內容也應組織成使搜索特定信息變得輕而易舉的結構。 Steve Konves建議您將文檔構造在單個鏈接的樹上：從根節點開始，該基因應放置在一個明顯的位置，供每個感興趣的用戶發現，所有其他項目都可以輕鬆訪問。該項目的README文件可以使整個樹的出色根節點非常有效。 >

>另外，如果您從軟件用戶收到幫助請求，則可以編寫答案並使它們在易於訪問的常見問題解答頁面中提供。這樣做會減少您花費幫助用戶的時間，但這也將使您更清楚地了解用戶最常需要的信息類型，以便您可以先記錄下來並將它們保持在文檔中的突出位置。

確保您的文檔是最新的，並且沒有錯誤

>輕鬆訪問您的軟件文檔非常好，但是如果用戶發現其內容已過時，或者示例代碼或指令會導致錯誤結果，那麼至少可以說這會令人沮喪。儘管如此，史蒂夫·康維斯（Steve Konves）建議您將文檔保持在代碼附近，例如，在源控制中。這樣，當開發人員更新代碼時，他們會注意到文檔材料，這使更新文檔的更新更有可能發生。

>另外，要最大程度地減少錯誤的發生，請徹底測試您在文檔中提供的說明和代碼樣本。

額外的提示和一些流行的示例

不要停止文檔。博客文章非常適合使您的軟件及其功能受到廣泛的潛在用戶的了解。使用您的博客來澄清您的產品的作用，提供用戶友好的教程，提示和技巧，演練，解釋更新等。您可以在專門用於軟件的獨立網站中包含您的博客 - 也許與論壇 - 一個強大的社區可以聚集和成長。

在我看來，這個更廣泛的文檔概念的一個很好的例子是由廣泛成功的JS動畫平台Greensock實現的，我發現自己使用了很多，尤其是因為它的網站使其易於使用且易於使用且易於使用結構化文檔，一個超級有用的論壇，博客文章，快速提示等等。

>

react和vue.js也可以算作很棒的例子。一旦您訪問了他們各自的網站，主頁就會告訴您每個庫在快速標語中有益於什麼，然後詳細介紹為什麼庫可以將其視為您項目的絕佳選擇。這兩個網站都可以使用柔和的介紹，說明性片段，簡短的任務開始使用代碼操場等工作。詳細說明如何獲得幫助，在生態系統上顯示信息，提供新聞或博客部分等。

>

>離開JS區域，進入具有出色網站的流行UI庫領域，我無法遺漏Bootstrap。在Bootstrap網站上，您會立即找到圖書館的用途以及如何快速入門，以及全面且結構良好的文檔和博客，以使用戶對新事物的最新信息保持最新。

結論

>編寫良好的文檔有其挑戰，但是如果您認為用戶可以實現軟件功能要容易得多，它肯定會付出一百倍。反過來，這有助於您的軟件的受歡迎程度，這使其具有吸引力，因此有可能引起一個願意花費時間深入學習的開發人員社區，並為其增長，穩定和長期做出貢獻用法。

經常詢問有關編寫軟件文檔的問題（常見問題解答）

>編寫軟件文檔時要考慮的關鍵要素是什麼？

在編寫軟件文檔時，要考慮目標受眾，文檔的目的以及編寫文檔的類型至關重要。所使用的語言應清晰，簡潔且易於理解。該文檔的結構良好，並具有邏輯信息流。在必要的情況下，包括圖表或屏幕截圖之類的視覺效果也很重要。最後，始終確保對文檔進行徹底審核和編輯，以進行準確性和清晰度。

>如何使我的軟件文檔對用戶友好？

使您的軟件文檔用戶友好，請使用簡單和清晰的語言。盡可能避免行話和技術術語。如果您必須使用它們，請確保您提供明確的定義。邏輯地組織您的內容，並使用標題和子標題使其易於瀏覽。包括一張目錄和一個較長文檔的索引。使用圖表，屏幕截圖和視頻之類的視覺效果來說明復雜的概念。

>有哪些不同類型的軟件文檔？

>

有幾種類型的軟件文檔，包括系統文檔，用戶文檔，用戶文檔，用戶文檔，和技術文檔。系統文檔提供了軟件系統的概述，包括其架構和數據流。用戶文檔提供了有關如何使用軟件並包含用戶手冊和幫助指南的說明。技術文檔旨在為開發人員提供，並包括代碼註釋，API文檔和開髮指南。

>應更新軟件文檔？軟體.這可能是由於添加了新功能，已修改現有功能或修復錯誤。定期審查文檔以確保其仍然準確和相關也是一個好主意。

>

我可以使用哪些工具來編寫軟件文檔？

>有許多用於編寫軟件文檔的工具，包括文字處理器，文檔生成器和專用文檔工具。一些流行的選項包括Microsoft Word，Google Docs，Doxygen和Sphinx。工具的選擇取決於您的特定需求和軟件的複雜性。

如何確保軟件文檔的質量？

確保軟件文檔的質量，始終查看並徹底編輯您的工作。考慮讓同事或專業編輯審查您的文檔。在整個文檔中使用一致的樣式和格式。確保信息準確，最新和相關。最後，考慮從用戶那裡獲取反饋以確定改進領域。

>視覺效果在軟件文檔中的作用是什麼？

視覺效果在軟件文檔中起著至關重要的作用。他們可以幫助說明復雜的概念，從而更容易理解。它們還可以分解大量文本，使文檔更可讀。視覺效果的示例包括圖表，屏幕截圖，流程圖和視頻。

>如何使我的軟件文檔更具吸引力？

使您的軟件文檔更具吸引力，使用對話性音調和主動語音。用視覺效果和子彈點分解大塊文本。使用示例和案例研究來說明概念。在適當的情況下包含交互式元素，例如測驗或練習。

在軟件文檔中一致性的重要性是什麼？

一致性在軟件文檔中很重要，因為它使文檔更易於閱讀和理解。它還使文檔具有專業的外觀。一致性適用於語言，樣式，格式和視覺效果。

>我如何提高我編寫軟件文檔的技能？

以提高您在編寫軟件文檔，定期練習寫作方面的技能。閱讀其他軟件文檔以向它們學習。參加有關技術寫作的課程或講習班。尋求有關您的工作的反饋，並接受批評。在軟件文檔中的最新趨勢和最佳實踐保持最新狀態。

>

以上是編寫第一個軟件文檔的指南的詳細內容。更多資訊請關注PHP中文網其他相關文章！