目前階段：
2021 年「Docs 季」計畫已於 2021 年 12 月 14 日結束。請參閱時間軸。
關於「Season of Docs」
文件季是由 Google 開放原始碼計畫辦公室管理的永續發展計畫。Season of Docs 的目標如下：
- 為開放原始碼專案提供支援，以便透過說明文件解決專案問題
- 讓技術作家有機會累積開放原始碼相關經驗
- 提高開放原始碼、說明文件和技術寫作相關知識的知名度
- 在開放原始碼說明文件中收集及分享有效指標相關資訊
如要進一步瞭解「影像故事季」計畫，請造訪網站。
2021 年計畫總覽
2021 年計畫異動
2019 和 2020 年間，各機構和技術文件撰寫者分別應徵 Google 文件季期間，技術文件撰寫專員和技術文件撰寫專員，和文件計畫管理員可相互媒合。許多機構提供輔導員與技術文件撰稿者合作。這些技術撰稿者依自己的所在地獲得獎學金。本計畫評估的是技術作家、導師和機構管理員對參與計畫的滿意程度，但未評估文件成果。
2021 年，技術文件季團隊對計畫進行了重大調整，將重點轉移至評估技術文件成果，並讓機構和技術撰稿人享有更大的彈性。
- 使用專案提案套用的機構，包括預算和建議指標
- 技術文件撰寫人員已不再透過 Google 申請與機構媒合，而是直接負責獲得認可的機構
- 獲選的機構會透過 Open Collective 收到補助金，用於支付技術作家的薪水
- 技術寫作者的薪資是由機構設定
- 機構提交最終評估和個案研究，並回答後續問卷調查
2021 年一般發現
機構組織
- 2021 年計畫的異動導致申請機構減少 (2021 年申請機構比 2020 年減少 30%)，但 2021 年機構管理員對計畫的滿意度略高於 2020 年 (93% 比 91%)
問題、doctype 和指標
- 大多數專案都著重於建立說明文件，以減輕維護者的負擔 (透過減少問題/問題) 和/或增加專案參與度 (無論是專案使用者或貢獻者)。
- 50% 的獲准機構製作了教學課程或操作說明內容。
- 超過 50% 的通過審查機構認為目前的文件不完整、雜亂或過時。
- 專案通常希望透過互動來評估說明文件的有效性，尤其是提出的問題越少，說明文件的訪客和參與專案的參與者越多。
- 截至 2022 年 11 月，30 個專案中有 25 個回應：
- 18 項專案表示自己已達到原始指標
- 5 個專案已達到修訂指標
- 2 項專案表示系統太快判定
參與計畫
- 招募、聘用和支付技術文件撰寫專員的費用，是機構管理員在本計畫中遇到的最大難題。
- 截至 2022 年 11 月，30 個機構中有 24 個回覆：
- 18 個機構仍在與當季文件技術文件撰寫人員合作 (無論是持續貢獻者，或是可回答問題的資源)
- 4 個機構與他們的「文件季」技術作家合作，並支付薪資
- 18 個機構仍在與當季文件技術文件撰寫人員合作 (無論是持續貢獻者，或是可回答問題的資源)
2021 年精選
- 多項專案表示，其技術文件撰寫人員希望在文件季結束後繼續處理專案
- Metanorma 收到許多合格的技術作家申請，因此他們找到了對應的資金，以便在計畫期間聘請額外一位作家，與 Docs 支援的作家合作
- Moja Global 發現社群對說明文件非常感興趣，因此設立了新的說明文件工作小組，讓更多貢獻者參與專案說明文件
2021 年摘要資料
2021 年，有 82 個機構提出申請，有 30 個開放原始碼機構獲準加入這項計畫。(如要瞭解選拔標準，請參閱「建立應用程式指南」)。如要查看完整的參與機構清單，請前往 Documentary Season 網站。所有 30 家獲選機構都提交了最終個案研究報告，完成 2021 年計畫的參與。
機構簡介
參與 2021 年文件季的機構代表了各種開放原始碼專案。2021 年同儕群組包括：
- 大型語言專案，例如 Julia、Perl 和 R
- 教育、氣候、金融科技、醫療保健、圖書館服務、機器學習、質譜、公共合約和機器人專案
- 以開發人員為重點的專案，包括混沌工程工具、模糊測試工具、聊天機器人 SDK、軟體組合分析管道、效能監控工具和視覺化程式設計工具
- Redocly 和 Metanorma 等說明文件工具的說明文件專案
Python 生態系統專案是最大的子類別。2021 年參與計畫的團隊包括 ArviZ、NumPy、MicroPython、PyMC3、PyTorch-Ignite 和 SymPy。
我們並未收集任何與專案相關的中繼資料 (例如創立日期、貢獻者的地理位置分佈、貢獻者人數或使用者族群規模)。
我們確實要求專案指出所使用的開放原始碼授權。
在開放原始碼專案和技術說明文件中，2021 年機構提出的說明文件問題都是相當常見的問題。
機構在 2021 年計畫中希望解決的主要問題包括：
請注意，組織可回報多個文件問題。如需更多詳細資訊，請參閱「2021 年 Docs 季」結果頁面，其中提供各機構的完整案例研究連結。
建立的文件類型
「教學課程」是 2021 年個案研究中最常提及的說明文件類型。
個案研究中提到的其他說明文件類型包括以文件為程式碼的管道、圖表、字典、樣式指南、常見問題、國際化、程式碼研究室、內容模型、模組、概念說明文件、錯誤訊息、使用者研究、Readme、知識庫。
其中有些類別模糊不清，一個說明文件專案可能包含多種文件類型或功能。
幾個專案特別參考了 Diátaxis 架構，以此做為規劃文件類型的指南。
如需更多詳細資訊，請參閱「2021 年 Docs 季」結果頁面，其中提供各機構的完整案例研究連結。
預算
2021 年的平均預算要求為 $10,200 美元，中位數為 $10,000 美元，只有三個機構申請並獲得最高金額的補助金 (15,000 美元)，另外三個機構則申請最低金額的補助金 (5,000 美元)。
指標
個案研究中列出的計畫，以及他們用來評估說明文件成效的指標。
前幾項建議指標如下：
其他建議指標包括 GitHub 星號、網頁停留時間、郵寄清單轉換次數、合格使用者測試、論壇的參與者人數、合作夥伴/志工/整合。
由於從完成技術寫作專案到提交個案研究之間過短，2021 年的研究團隊大多無法收集到足夠資料，因此無法判斷是否已達到初始指標。
如需更具體的資訊，請參閱「2021 年文件季別」結果網頁，裡面有各機構的完整個案研究連結。
與技術文件寫作人員合作
2021 年「文件季」計畫最大的變動，是與技術作家合作的專案方式。在早期，技術作家直接向 Google 申請，然後由計畫管理員為他們安排專案，並直接向 Google 領取固定津貼。
2021 年，直接參與專案的技術文件撰稿者決定了技術文件撰稿人酬勞，而這筆預算是透過文件的 Open Collective 基金一季支付。
參與 2021 年計畫的專案大多沒有招募或聘用技術作家的經驗，許多專案也表示這部分的程序需要更多支援。為了回應這項意見回饋，季節性文件團隊在計畫指南中新增了技術作家協議建立說明文件。
招募建議
專案需要為其他有興趣參與「文件」季節計畫的專案提供建議。主要的招募建議如下：
- 請盡早提供技術作家的招募資料，甚至在您加入計畫前就提供。請社群成員推薦可能的候選人。
- 在專案管道外廣泛分享。使用多元包容的用語，並直接鼓勵屬於弱勢族群的候選人提出申請。
- 瞭解哪些工具對說明文件製作程序至關重要，並招募具備使用這些工具經驗的技術作家。
- 請向技術作家明確說明成果和里程碑、溝通管道和回報時間、付款程序和時間。
- 考慮投資社群會員，協助他們成長為技術文件撰稿人員，在當季的文件技術文件撰寫人員擔任指導和輔導時。
- 在計畫期間，請預留比預期更多的時間，讓技術作家上手、回答問題，並提供支援，尤其是當技術作家沒有相關專案領域的經驗時。
- 記錄招募、錄取和新進人員的 onboarding 流程，以便日後的專案使用。
(注意：個案研究中僅列出部分專案，在當中招募技術文件撰稿人候選人。)
與技術作家合作時常見的問題
多個專案的技術作家因 COVID 或其他疾病，或是因疫情而產生的家庭責任而離開。部分專案回報了時區不符或網路連線問題導致的通訊問題。
專案發現，他們低估了加入社群或設定專案文件工具鍊的難度。
有些專案是因為 Open Collective 的銀行問題，或是作家所在國家/地區的付款限制，導致技術文件寫作人員的付款延誤。
有關 Open Collective 費用的計畫文件未清楚指出：Google 已負擔初次轉帳至專案的開放式集體交易手續費，但不含其他付款管道產生的交易手續費 (例如貨幣換算費用)。我們會在日後的計畫中，盡力在說明文件中說明清楚這一點。
後續追蹤問卷調查
在文件季計畫中，專案被要求參加後續的問卷調查。我們在 2022 年 5 月、8 月和 11 月共寄出三份問卷調查。
在後續問卷調查中，我們請專案確認提案和案例研究的連結是否仍有效。這份問卷也包含了有關專案成效的問題 (根據個案研究中設定的指標)，以及專案技術作家的持續參與和報酬：
- 您還在與 Google 文件技術文件撰寫專員合作嗎？
- 如果技術作家仍在處理你的專案，他們是否會獲得任何補償？
- 此時，您認為說明文件專案已順利完成嗎？
未來問題
一如往常，我們越是瞭解開放原始碼的說明文件，就越想進一步瞭解！我們希望在未來的季度中瞭解：
- 專案網域是否與 doctype 或指標選項相關
- 哪些技術作家招募和新手上路做法最能有效完成專案，並留住技術作家
- 評估文件成效的合理時間表
雖然我們有很多問題想調查，但也希望能尊重參與文件季的開放原始碼專案管理員和維護者的時間。本計畫的首要目標，就是協助專案解決說明文件相關問題。