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

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

撰寫文檔，從項(xiàng)目第一天就開始

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

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

文檔及代碼

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

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

請(qǐng)記住，如果不遵循規(guī)范化的實(shí)踐，每個(gè)文檔都會(huì)不同。這可能會(huì)導(dǎo)致一些混亂，使人們難以獲取正確的信息。

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

整理混亂的開源文檔

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

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

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

文檔類型：

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

通過使用風(fēng)格指南，文件的整體前提將以統(tǒng)一的語言風(fēng)格傳達(dá)給用戶。但是，這些文件畢竟是由一個(gè)技術(shù)作家團(tuán)隊(duì)準(zhǔn)備的，它們的寫作風(fēng)格可能會(huì)沖突，因?yàn)閷懽黠L(fēng)格是因人而異的。那么，如何才能使文檔規(guī)范化呢?

規(guī)范化文檔

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

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

反饋和自動(dòng)審查

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

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

文檔眾包

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

始終開發(fā)以用戶為中心的文檔，標(biāo)明每個(gè)項(xiàng)目的目的。同時(shí)，打造學(xué)習(xí)課程來幫助新的貢獻(xiàn)者。

帶著目的編寫文檔

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

• 這個(gè)文檔的目標(biāo)是什么？
• 需要傳遞的信息是什么？
• 你希望用戶在這之后采取什么行動(dòng)？
• 我與讀者分享的價(jià)值觀是什么？
• 我的文檔風(fēng)格是否簡(jiǎn)潔、一致？

定義一致的內(nèi)容策略

一致的內(nèi)容策略有助于確保文檔工作和項(xiàng)目基礎(chǔ)設(shè)施的長期愿景。它可以圍繞以下兩個(gè)主要方面：

• 資源：包括項(xiàng)目文檔、案例研究和白皮書、項(xiàng)目架構(gòu)等
• 品牌內(nèi)容：博客和特邀帖子、新聞和社區(qū)故事、學(xué)習(xí)課程等

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