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