關於「Season of Docs」
文件季是由 Google 開放原始碼計畫辦公室管理的永續發展計畫。Season of Docs 的目標如下：
- 為開放原始碼專案提供支援，協助解決專案問題
- 讓技術作家有機會累積開放原始碼相關經驗
- 提高開放原始碼、文件和技術寫作相關知識的知名度
- 在開放原始碼說明文件中收集及分享有效指標相關資訊
如要進一步瞭解「Documentary Season」計畫，請前往網站。
2021 年計畫簡介
2021 年計畫異動
在 2019 年和 2020 年，機構和技術作家各自申請「季節性文件」計畫，技術作家會由「季節性文件」計畫管理員與機構配對。機構提供導師與技術作家合作，並根據技術作家所在地點提供津貼。本計畫評估的是技術作家、導師和機構管理員對參與計畫的滿意程度，但未評估文件成果。
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 個機構與他們的 Docs 技術作家合作，並支付薪資
- 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 年 Docs 季」結果頁面，其中提供各機構的完整案例研究連結。
與技術文件寫作人員合作
2021 年「文件季」計畫最大的變動，是與技術作家合作的專案方式。在早期，技術作家直接向 Google 申請，然後由計畫管理員將他們與專案配對，並直接向 Google 領取固定津貼。
2021 年，技術作家直接申請加入專案，專案會設定技術作家的薪資預算，並透過「季節性文件」開放式集資基金支付。
參與 2021 年計畫的專案大多沒有招募或聘用技術作家的經驗，許多專案也表示這部分的程序需要更多支援。為了回應這項意見回饋，Docs 季團隊在計畫指南中新增了技術作家協議建立說明文件。
招聘建議
我們請專案團隊為其他有意參與「文件季」的專案提供建議。主要的招募建議如下：
- 請盡早提供技術作家的徵才資料，甚至在加入計畫前就提供。請社群成員推薦可能的候選人。
- 在專案管道外廣泛分享。使用包容的用詞，直接鼓勵少數族裔應徵者申請職缺。
- 瞭解哪些工具對說明文件製作程序至關重要，並招募具備使用這些工具經驗的技術作家。
- 請向技術作家說明預期成果和里程碑、通訊管道和回報時間、付款程序和時間。
- 建議您透過 Docs 技術作家季節，為社群成員提供指導和訓練，協助他們成為技術作家。
- 在計畫期間，請預留比預期更多的時間，讓技術作家上手、回答問題並提供支援，尤其是當技術作家沒有相關專案領域的經驗時。
- 記錄招募、錄取和新進人員的 onboarding 程序，以便日後的專案使用。
(注意：並非所有個案研究都指出他們招募技術作家候選人的專案)。
與技術作家合作時常見的問題
多個專案的技術作家因 COVID 或其他疾病，或是因疫情而產生的家庭責任而離開。部分專案回報了時區不符或網路連線問題導致的通訊問題。
專案發現，他們低估了加入社群或設定專案文件工具鍊的難度。
由於 Open Collective 的銀行問題，或作者所在國家/地區的付款限制，導致部分專案的技術作家薪資延遲發放。
關於 Open Collective 費用的計畫說明並不清楚：Google 會負擔 Open Collective 交易費用，也就是將資金初始轉移至專案的費用，但不會負擔其他付款管道 (例如貨幣換算費用) 收取的交易費用。我們會在日後的計畫說明文件中，更清楚說明這項規定。
後續問卷調查
在「季節性說明文件」計畫中，我們要求專案參與後續問卷調查。我們在 2022 年 5 月、8 月和 11 月共寄出三份問卷調查。
在後續問卷調查中，我們請專案確認提案和案例研究的連結是否仍有效。這份問卷也包含了有關專案成效的問題 (根據個案研究中設定的指標)，以及專案技術作家的持續參與和報酬：
- 你是否仍在與「季節性文件」技術作家合作？
- 如果技術作家仍在處理你的專案，他們是否會獲得任何補償？
- 你是否認為目前的文件製作專案是成功的？
未來的問題
一如往常，我們越是瞭解開放原始碼的說明文件，就越想進一步瞭解！我們希望在未來的季度中瞭解：
- 專案網域是否與 doctype 或指標選項相關
- 哪些技術作家招募和新手上路做法最能有效完成專案，並留住技術作家
- 評估文件成效的合理時間表
雖然我們有很多問題想調查，但也希望能尊重參與文件季的開放原始碼專案管理員和維護者的時間。本計畫的首要目標，就是協助專案解決說明文件相關問題。