編寫對社區真正有用的文檔

建立良好的文檔可能是困難的，但它對有效的溝通至關重要。遵循這個框架來編寫並與正確的人分享文檔。

成功和可持續的項目，與那些消失無蹤的項目有什麼不同？答案是 —— 社區。社區是開源項目的發展動力，而文檔是構建社區的基石之一。也就是說，文檔的意義不僅僅在於文檔本身。

建立好的文檔可能很困難。用戶不願意閱讀文檔，因為它不易查找，它很快就過時了，它冗長，或者它不全面。

開發團隊不寫文檔，因為他們陷入了「對我來說顯而易見，所以對所有人都顯而易見」的陷阱。他們不寫，因為他們忙於開發項目。要麼是需求變化太快了，要麼是開發得還不夠快。

但是好的文檔仍然是團隊和項目之間最好的溝通工具。考慮到項目隨著時間的推移往往會變得更大，這一點尤其重要。

文檔可以是團隊或公司內部的唯一真理。這在協調人們朝著共同的目標前進，以及在人們轉移到不同的項目時保留知識方面非常重要。

那麼，要如何為一個項目寫出合適的文檔，並與正確的人分享呢？

什麼是成功的社區文檔？

要想在你的社區文檔編寫中取得成功，你需要：

• 規劃你的路徑
• 使其清晰簡單
• 靈活變通，根據具體情況調整路徑
• 做版本控制

靈活並不意味著混亂。許多項目之所以成功，就是因為它們組織得很好。

James Clear（《 原子習慣 Atomic Habits 》一書的作者）寫道：「你並不是提升到了你目標所在的水平，而是降低到你整個系統所在的水平。」一定要組織好過程，使水平足夠高，才能取得成功。

設計流程

文檔本身就是一個項目。你可以把寫文檔當作寫代碼一樣。事實上，文檔可以是一個產品，而且是一個非常有價值的產品。

這就意味著你可以採用與軟體開發相同的流程：分析、獲取需求、設計、實現和維護，把文檔作為你的一個流程對待。

在設計流程時，要從不同的角度考慮。不是所有的文檔都適用於所有人。

大多數用戶只需要一個了解項目概況的文檔，而 API 文檔則是留給開發者或高級用戶的。

開發者需要了解庫和函數的文檔。用戶則更需要看到示例、操作指南，和項目與其他軟體相配合的架構概述。

總之，在創建任何流程之前，你必須確定你需要什麼：

• 關注的群體： 包括開發者、集成商、管理員、用戶、銷售、運營、高管
• 專業水平： 要考慮到初級、中級和高級用戶
• 詳細程度： 既要有高層級的概述，也要有技術細節，所以要考慮如何呈現這些內容
• 路徑和入口： 人們如何找到文檔，如何使用文檔

當你思考這些問題時，它可以幫助你構建你想通過文檔傳達的信息的結構。它定義了文檔中必須包含的內容的清晰指標。

下面是如何圍繞文檔建立一個流程的方法。

編碼約定

代碼本身應該有意義。文檔應通過良好的類名、文件名等來表達出來。通過思考以下內容，創建通用的編碼標準和自我註解的編碼過程：

• 變數命名約定
• 通過使用類、函數命名方案使名稱易於理解
• 避免深度嵌套，或 根本不嵌套
• 不要簡單地複製和粘貼代碼
• 不應使用長方法
• 避免使用幻數（改用常量）
• 使用提取的方法、變數等
• 使用有意義的目錄結構、模塊、包和文件名

開發時測試

測試不僅僅是關於代碼應該如何工作。它還涉及如何使用 API、函數、方法等。編寫良好的測試可以揭示基本用例和邊緣用例。甚至還有一種 測試驅動開發 的實踐，專註於在代碼開發之前創建測試用例（應該測試什麼以及如何測試的分步場景）。

版本控制

版本控制（即使是對文檔進行版本控制）可以幫助你跟蹤更改的邏輯。它可以幫助你回答為什麼這麼修改。

確保提交期間的注釋能解釋為什麼進行更改，而不是進行了哪些更改。

編寫文檔過程越吸引人，就會有更多的人參與其中，為它添加創造力和樂趣。你應該通過以下方式考慮文檔的可讀性：

• 軟體代碼約定
• 圖表和圖形（也通過文字進行解釋）
• 思維導圖
• 概念圖
• 信息圖表
• 圖片（突出顯示重要的部分）
• 短視頻

通過使用不同的交流方式，你可以提供更多的方式來參與文檔。這有助於防止誤解（不同的語言，不同的含義）和有助於通過不同的學習方式進行學習。

以下是一些用於創建文檔的軟體工具：

• Javadoc、Doxygen、JsDoc 等： 許多語言都有自動化的文檔工具，以幫助捕獲代碼中的主要功能
• Web 鉤子和 CI/CD 引擎： 允許持續發布文檔
• Restructured Text、Markdown、Asciidoc： 文件格式和處理引擎，幫助你從純文本文件中生成美觀且實用的文檔
• ReadTheDocs： 是一個可以和公共 Git 存儲庫聯動的文檔託管主機
• Draw.io、LibreOffice Draw、Dia： 製作圖表、圖形、思維導圖、路線圖、計劃、標準和指標等
• Peek、Asciinema： 記錄終端命令操作
• VokoscreenNG： 錄製屏幕和滑鼠點擊操作

文檔很重要

編寫文檔的過程和協議與項目本身同樣重要。最重要的是，它把項目的信息和項目的創造傳達到位，更加令人興奮。

快速進入項目和流程，以及了解一切是如何工作的，是文檔一個重要的功能。它有助於確保眾人持續參與。通過在團隊中構建一種「語言」，可以簡化流程，更清晰地理解所要做的事情。

文檔旨在傳達價值，即無論是通過團隊成員還是通過應用程序的用戶的言行，來展示出某些東西。

要將這個過程視為一個連續的整體，並在其中融合使用溝通、流程和文檔的方式。

文檔是一種溝通手段。

（題圖：MJ:document development illustration in high resolution, very detailed）

via: https://opensource.com/article/23/3/community-documentation

作者：Olga Merkulova 選題：lkxed 譯者：alim0x 校對：wxy

本文由 LCTT 原創編譯，Linux中國 榮譽推出

本文轉載來自 Linux 中國: https://github.com/Linux-CN/archive