文件並不是開源專案開發的附屬品 | Linux 中國

語言: CN / TW / HK

有些專案長期保持活躍,有些專案卻過早消亡 —— 這兩者的區別往往在於它們的文件。嚴謹、聰明的文件可以給你的專案帶來它所需要的動力。

(本文字數:3032,閱讀時長大約:5 分鐘)

有些專案長期保持活躍,有些專案卻過早消亡 —— 這兩者的區別往往在於它們的文件。嚴謹、聰明的文件可以給你的專案帶來它所需要的動力。你應該把文件工作視為一項主要工作,把它與開發相提並論,下面我將說明這麼做的理由和正確的做法。

經常會有開發者簡單地認為他們的程式碼的“ 自我描述(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中國 榮譽推出