有些項目長期保持活躍，有些項目卻過早消亡 —— 這兩者的區(qū)別往往在于它們的文檔。嚴謹、聰明的文檔可以給你的項目帶來它所需要的動力。你應該把文檔工作視為一項主要工作，把它與開發(fā)相提并論，下面我將說明這么做的理由和正確的做法。

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

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

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

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

文檔及代碼

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

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

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

哪些東西會被歸類為混亂呢?當大多數文件都不遵循規(guī)范實踐時，不一致就會產生，從而導致更大的混亂!那么，如何整理混亂的開源文檔呢?

整理混亂的開源文檔

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

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

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

文檔類型：

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

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

規(guī)范化文檔

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

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

反饋和自動審查

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

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

文檔眾包

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

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

帶著目的編寫文檔

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

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

定義一致的內容策略

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

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

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