作為開發人員，您的驕傲和喜悅是您的代碼。它是可讀的，符合乾燥原則，反映了最佳實踐，最終產品是一個很好的工具，可以解決其目標用戶的某種問題。但是，無論您在代碼中投入了多少工作，如果您的軟件沒有文檔，或者您將文檔作為事後思考，並且對其進行了很少的重視處理，那麼用戶可能會很少能找到使用它的樂趣，並且最終選擇了不同的，更易於用戶友好的產品。
>在本文中，您會發現許多實用的指導原則，可以通過編寫第一個軟件文檔來啟動並運行。
參考您的軟件，Mike Pope有一個合適的說法：如果沒有記錄，則不存在。
為什麼？ 好吧，只是以我的個人經驗為例，我正在瀏覽網絡，以尋找新的JavaScript動畫庫來嘗試，我遇到了一個我真正喜歡的功能的描述。但是，沒有文檔，甚至沒有入門部分，而只是一個裸露的API頁面，幾乎沒有解釋或示例。您認為我最終使用了該庫嗎？當然，我沒有。我對此感到非常沮喪，以至於我繼續對自己更有意義的事情。>
的問題為什麼好的javascript庫失敗，nicholos zakas給出了以下答案：
缺乏文檔。無論您的圖書館多麼美妙以及它的設計多麼聰明，如果您是唯一了解它的人，它都不會有任何好處。文檔不僅意味著自動化的API參考，還意味著註釋的示例和深入的教程。您需要所有這三個，以確保您的庫可以輕鬆地採用。
>您的軟件文檔至關重要的另一個重要原因是它們是您當前的自我和未來自我之間以及當前自我與其他開發人員之間的交流工具，這些工具最終可能會發現自己從事您的軟件。即使您編寫可讀和評論的代碼，這並不一定意味著您仍然會在六個月的時間內清楚您為什麼寫函數或以此為代碼的任何其他代碼。
> 如果您的軟件沒有很好的文檔可以使用。>文檔允許您在代碼背後傳輸
>當然，您希望人們使用您的代碼，並最終能夠對其進行更新並改進它。這些都是為您的產品背後的支持社區增長的重要因素，這對於獲得穩健性，成熟度和成功很重要。為什麼。以相同的方式，代碼註釋解釋了為什麼，而不是>>，文檔的目的相同。 - 撰寫文檔的初學者指南>
誰軟件文檔適用於
>
撰寫任何內容時，請確保您的聽眾是誰。文檔也不例外。這樣做會闡明您的觀眾可能面臨的問題，這可能對您的產品或使用產品的先決條件。此信息對於您創建內容和使用的語言的方式至關重要。>
在您的文檔中包含什麼
>對您的軟件的功能以及它解決的問題的解釋
初學者會喜歡在您的軟件文檔中找到一個教程。教程旨在向用戶展示如何使用您的軟件完成項目，以便他們可以快速了解自己可以做的事情。
>課程
，可以將讀者藉助一系列步驟完成某種項目。它們是您的項目所需的，以便向初學者展示他們可以通過它實現的目標。 -daniele procida
操作方法指南可幫助用戶使用軟件解決現實世界任務。 Procida將它們與食譜進行了比較，因為它們是您給用戶提供的方向，以便他們可以成功實現某個目標。與針對完整初學者的教程不同，如何指導用戶已經擁有一些對功能，工具以及如何執行簡單任務的基本知識。
參考指南參考指南是機械的技術描述，以及如何操作它。 -
daniele procida>這是您在大多數項目中可能會找到的文檔。開發人員傾向於編寫它，因為他們對自己的代碼了解全部了解。 >說明
的解釋是您認為與您對軟件的高層理解有關的特定主題的深入研究或討論。關於解釋，Procida指出 -
這部分文檔很少是明確創建的，而是在其他部分中分散了解釋的片段。有時，該部分存在，但有一個名稱，例如
>
>主題不是由您要完成的特定任務（例如如何指南）或您希望用戶學習的內容（例如教程）來定義的。它不是由參考材料而定義的。它的定義是由您認為是一個合理的領域，以便>>>>>最好讓您易於找到軟件文檔。您可以將某些SEO技術與某些營銷策略一起使用，以便盡可能多的用戶可以掌握它。一次，因此討論的主題有時可能是任意的。
您需要注意的事情> > >讓我們瀏覽一些有用的指針，以使您的文檔用戶友好且相關。 使您的文檔可發現
>
>另外，如果您從軟件用戶收到幫助請求，則可以編寫答案並使它們在易於訪問的常見問題解答頁面中提供。這樣做會減少您花費幫助用戶的時間，但這也將使您更清楚地了解用戶最常需要的信息類型，以便您可以先記錄下來並將它們保持在文檔中的突出位置。
確保您的文檔是最新的，並且沒有錯誤>另外，要最大程度地減少錯誤的發生，請徹底測試您在文檔中提供的說明和代碼樣本。
額外的提示和一些流行的示例
>
react和vue.js也可以算作很棒的例子。一旦您訪問了他們各自的網站，主頁就會告訴您每個庫在快速標語中有益於什麼，然後詳細介紹為什麼庫可以將其視為您項目的絕佳選擇。這兩個網站都可以使用柔和的介紹，說明性片段，簡短的任務開始使用代碼操場等工作。詳細說明如何獲得幫助，在生態系統上顯示信息，提供新聞或博客部分等。>
>離開JS區域，進入具有出色網站的流行UI庫領域，我無法遺漏Bootstrap。在Bootstrap網站上，您會立即找到圖書館的用途以及如何快速入門，以及全面且結構良好的文檔和博客，以使用戶對新事物的最新信息保持最新。>編寫良好的文檔有其挑戰，但是如果您認為用戶可以實現軟件功能要容易得多，它肯定會付出一百倍。反過來，這有助於您的軟件的受歡迎程度，這使其具有吸引力，因此有可能引起一個願意花費時間深入學習的開發人員社區，並為其增長，穩定和長期做出貢獻用法。
使您的軟件文檔用戶友好，請使用簡單和清晰的語言。盡可能避免行話和技術術語。如果您必須使用它們，請確保您提供明確的定義。邏輯地組織您的內容，並使用標題和子標題使其易於瀏覽。包括一張目錄和一個較長文檔的索引。使用圖表，屏幕截圖和視頻之類的視覺效果來說明復雜的概念。
>
>應更新軟件文檔？軟體.這可能是由於添加了新功能，已修改現有功能或修復錯誤。定期審查文檔以確保其仍然準確和相關也是一個好主意。
>>有許多用於編寫軟件文檔的工具，包括文字處理器，文檔生成器和專用文檔工具。一些流行的選項包括Microsoft Word，Google Docs，Doxygen和Sphinx。工具的選擇取決於您的特定需求和軟件的複雜性。
>
以上是編寫第一個軟件文檔的指南的詳細內容。更多資訊請關注PHP中文網其他相關文章！
