文檔並不是開源項目開發的附屬品

經常會有開發者簡單地認為他們的代碼的「 自我描述 self-documented 」已經足夠了，繼而認為額外的文檔是沒有必要的。這種過度的自信會讓項目付出很大的代價。匱乏或差勁的文檔會扼殺你的項目。沒有適當的文檔，用戶將無法理解項目的目標以及正確的工作流程。這可能會導致人們對採用你的開源產品產生一些疑慮。

撰寫文檔，從項目第一天就開始

文檔不應該是次要的工作，它應該是與代碼開發和管理同等的主要任務。隨著內容以 Community Threads、Stack Overflow 和 Quora 問答等形式的廣泛傳播，文檔承擔了「 信息源 source of truth 」的角色。它應該滿足那些想參考一手資料的貢獻者的需要，並給工程師提供必要的參考支持。它還應該與利益相關者溝通基本計劃。一個好的文檔可以確保產品的持續改進和發展。

當發布一個軟體產品時，我們不僅要發布代碼，還要發布好的文檔。這給我們帶來了一個最重要的概念，大多數良好維護了文檔的開源項目都遵循這個概念 —— 「 文檔即代碼 Documentation as code 」。

文檔及代碼

今天，文檔不再被存儲為微軟 Word 或 PDF 文件。新的需求是版本控制文檔，其中所有的文檔都是通過版本控制系統添加的，並持續發布。這個概念因 Read the Docs（LCTT 譯註：一個文檔創建、託管和瀏覽的平台）而流行，現在已經成為大多數文檔團隊的內容策略的重要組成部分。

像 Bugzilla 和 GitHub 議題 Issue 這樣的工具可以用來跟蹤待處理的文檔工作，並從維護者和用戶那裡獲得反饋以驗證文檔的發布。外部審查可以用來驗證文檔作品，並持續發布文檔。這就保證了除代碼外，文檔也能不斷改進並快速發布。

請記住，如果不遵循規範化的實踐，每個文檔都會不同。這可能會導致一些混亂，使人們難以獲取正確的信息。

哪些東西會被歸類為混亂呢？當大多數文件都不遵循規範實踐時，不一致就會產生，從而導致更大的混亂！那麼，如何整理混亂的開源文檔呢？

整理混亂的開源文檔

遵循一個「文檔風格指南」是很重要的。風格指南是創建和展示內容的指導方針的集合。無論你是一個獨立的作家還是一個大型文檔團隊的成員，它都有助於在你的文檔中保持一致的風格、口音和語氣。

有幾個流行的風格指南，如《紅帽風格指南》、《谷歌文檔風格指南》和《蘋果風格指南》。如何選用？首先要從定義你的需求開始。如果你的要求與其他開源項目沒有太大區別，你可以遵循一個現成的風格指南，或者你也可以先選一個，然後在它的基礎上根據自身需要做一些修改。大多數與語法有關的準則和內容規則可能是通用的，但整體術語可能會有所不同。

你還需要在你的項目中自動採用這些風格指南。為此，你可以使用 Vale，它集成了本地的持續集成（CI）服務，該服務能幫助你確保文檔嚴格遵循風格指南。

文檔類型

• 自述文件：包含基本的安裝和使用說明，這也是任何開源文檔中最重要的部分之一。它是潛在的用戶/開發者與項目之間的第一個連接點。
• 參考指南：可能包括一些基本的參考資料，以便幫助你快速上手，或者是與項目貢獻相關的文檔。
• 用戶文檔：是最基本的文檔，它描述了項目的使用方式。如果沒有用戶文檔，大多數人就會對如何使用該項目感到迷茫。
• 開發文檔：旨在支持開發團隊在項目中不斷取得新的進展。它還應該為內部開發工作提供一個良好的途徑，並確保功能被很好地傳達給股東。
• 社區內容：包括基本的博客、視頻和外部內容，旨在為那些想進一步了解項目的社區成員提供支持。

通過使用風格指南，文件的整體前提將以統一的語言風格傳達給用戶。但是，這些文件畢竟是由一個技術作家團隊準備的，它們的寫作風格可能會衝突，因為寫作風格是因人而異的。那麼，如何才能使文檔規範化呢？

規範化文檔

當涉及到規範化文檔時，有許多方法可以採取。第一個方法顯然是創建適用於各種角色的預定義模板。這些模板可以用來記錄新的功能、識別錯誤和問題，以及更新變更日誌以適應正在增加的新內容。

如果你採用的是基於 Git 的工作流，試著開發一個規範的工作流程來發布你的文檔。最規範的工作流是： 復刻 fork 發布文檔的倉庫，在本地分支上添加你的修改，推送這些修改，提出請求並要求對其進行審查。規範化文檔的一個好處就是帶來更好的反饋和審查過程。

反饋和自動審查

規範化使得你能夠得到用戶的反饋並生成自動的審查，可以參考這些反饋來改進項目和文檔。通過這些反饋，你也可以評估所分享的信息對用戶是否有意義。像 GitBook 這樣的文檔平台會提供合適的反饋服務，這有助於驗證文檔是否有用。

始終尋求 主題專家 subject matter expert （SME）對文檔的反饋，他們可以是利益相關者、開發者、工程師，甚至是外部貢獻者。你也可以使用自動測試和 CI 來驗證你的文檔是否遵循風格指南。

文檔眾包

如果你想開源你的文檔，最好的方法也許是提供一個快速入門指南。它可以像 CONTRIBUTING.md 那樣簡單，基本上只要說明該如何設置項目並為其作出貢獻/單純使用它即可。

始終開發以用戶為中心的文檔，標明每個項目的目的。同時，打造學習課程來幫助新的貢獻者。

帶著目的編寫文檔

始終帶著目的編寫文檔。它是最基本的寫作策略之一，它定義了你編寫某個特定文檔的理由，而非方式。首先回答以下問題：

• 這個文檔的目標是什麼？
• 需要傳遞的信息是什麼？
• 你希望用戶在這之後採取什麼行動？
• 我與讀者分享的價值觀是什麼？
• 我的文檔風格是否簡潔、一致？

定義一致的內容策略

一致的內容策略有助於確保文檔工作和項目基礎設施的長期願景。它可以圍繞以下兩個主要方面：

1. 資源：包括項目文檔、案例研究和白皮書、項目架構等
2. 品牌內容：博客和特邀帖子、新聞和社區故事、學習課程等

每個開源項目都應該有適當的文檔，以說明它能為用戶提供的功能，這樣用戶就可以選擇最合適的解決方案。適當的文檔可以傳達正確的信息，也可以讓其他開發者貢獻力量來進一步加強和改進項目。雖然聽起來很簡單，但只有做對了，文檔才能成功。而你的項目，反過來，只有在你的文檔正確的情況下才能成功，所以永遠不要低估它的目標或過程！

策劃：Laveesh Kocher

via: https://www.opensourceforu.com/2022/04/documentation-isnt-just-another-aspect-of-open-source-development/

作者：Harsh Bardhan Mishra 選題：lkxed 譯者：lkxed 校對：wxy

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

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