Season of Docs は、Google オープンソース プログラム オフィスが管理する持続可能性プログラムです。Season of Docs の目標は次のとおりです。
- オープンソース プロジェクトのサポートを提供し、ドキュメントでプロジェクトの問題を解決する
- テクニカル ライターにオープンソースの経験を積む機会を提供する
- オープンソース、ドキュメント、テクニカル ライティングの認知度を高める
- オープンソースのドキュメントで、効果的な指標に関する情報を収集して共有する
Season of Docs の詳細については、プログラムのウェブサイトをご覧ください。
2022 年のプログラムの概要
Season of Docs の仕組み
Season of Docs では、組織はプロジェクト提案書を提出して応募します。プロジェクト提案には、次の内容が含まれます。
- 組織に関する情報
- プロジェクトが直面している問題の説明
- プロジェクトでドキュメントを使用して問題を解決する方法
- プロジェクトでドキュメントの有効性を測定する方法（指標）
- 作業のタイムライン
- プロジェクトの予算
- 組織が同様のプログラムに参加した経験など、Season of Docs の管理者がプロジェクトと問題を理解するのに役立つその他の情報
プログラムへの参加が承認されると、組織はテクニカル ライターを直接採用します。Season of Docs は、Open Collective を使用して組織に資金を提供し、組織は Open Collective を介してテクニカル ライターに支払います。プロジェクトの予算とお支払いは透明性が高く、予算は Season of Docs サイトで公開されている組織のプロジェクト提案に含まれており、お支払いは Season of Docs Open Collective アカウントで確認できます。
ケーススタディ レポートを提出すると、組織はプログラムを完了したとみなされます。また、プログラム期間中は毎月の評価を、プログラム終了後の 1 年間は四半期ごとのフォローアップ アンケートへの回答をお願いしています。
2022 年のハイライト
「新しいドキュメントをリリースした後、Casbin と Casdoor への毎日のアクセス数がほぼ 2 倍になり、直帰率が約 30% 減少しました。」- Casbin
「このプロジェクトの嬉しい成果は、[テクニカル ライター] がコミュニティでリーダーシップを発揮するようになったことです。現在、両方のコントリビューターがワーキング グループとコミュニティ ミーティングを主導し、プロジェクトの設計とメンテナンスにも貢献しています。」- moja-global
「[GSoD] のおかげで、通常のセットアップでは非常に難しい、2 人の優秀なテクニカル ライターを採用できました。彼らは OpenMined の OS への貢献を続けており、私たちは彼らと素晴らしい仕事の経験を積んでいます。」- OpenMined
「また、新しいマニュアルは、計算質量分析法を初めて使用するユーザーにとって非常に使いやすくなっています。この点を説明すると、CZI の助成金は、歴史的に恵まれない個人にも奨学金を提供しています。また、一部の受賞者は、新しい OpenMS マニュアルを使用して 6 週間のインターンシップ期間をスタートさせ、新しいマニュアルについて肯定的なレビューを寄せています。」- OpenMS
2022 年の概要データ
2022 年の Season of Docs プログラムでは、67 件の応募の中から 31 件のプロジェクトが承認され、30 件のプロジェクトがプログラムを完了しました。承認された 31 の組織のうち、17 の組織は再申請でした。
承認された 31 件のプロジェクトで、58 人のテクニカル ライターが採用されました。190 人以上のテクニカル ライターが、Season of Docs GitHub リポジトリに連絡先情報とポートフォリオへのリンクを追加して、プログラムへの参加に関心があることを示しました。
2022 年のプログラムの場合:
- 100% の組織が申請プロセスに満足している
- 100% の組織が、プログラムのウェブサイトのドキュメント/コンテンツに満足している
- 93% の組織がこのプログラムで良い結果を得ています
- 90% の組織がドキュメント プロジェクトは成功したと感じている
組織について
Season of Docs 2022 に参加した組織は、さまざまなオープンソース プロジェクトを代表していました。2022 年のコホートには、以下が含まれていました。
- AsyncAPI や SpyderIDE などの開発ツール
- Julia、LFortran、R、p5.js などのプログラミング言語とフレームワーク
- CERN-HSF や SymPy などの科学プロジェクト
- Mautic、Open Food Facts、Talawa、Ushahidi などのエンドユーザー アプリケーション
- ExpressLRS や Open-RMF などのハードウェア プロジェクトやロボット プロジェクト
- GeomScale、GeomStats、OpenMined、Weaviate などのデータ プロジェクト
- cert-manager、NimbleEdge、Cilium などのクラウド プロジェクトとインフラストラクチャ プロジェクト
プロジェクトに関するメタデータ（設立日、投稿者の地理的分布、投稿者の数、ユーザーベースの規模など）は収集していません。
プロジェクトで使用したオープンソース ライセンスを示すようお願いしました。
ドキュメント プロジェクトについて
ドキュメントに関する問題
2022 年のプログラムで組織がドキュメントで解決したいと考えていた主な問題は次のとおりです。
組織は複数のドキュメントの問題を報告できます。詳しくは、Season of Docs 2022 の結果ページをご覧ください。このページには、各組織の元のプロジェクト提案と完全なケーススタディへのリンクが掲載されています。
作成されたドキュメントの種類
2022 年のケーススタディで最も多く言及されたドキュメント タイプは、How-to ドキュメントでした。
ケーススタディで言及されたその他のドキュメント タイプには、次のようなものがあります。
- クイックスタート
- 用語集
- よくある質問
- ナレッジベース
- コンポーネント
- ブログ/ソーシャル メディアのコンテンツ
- メンテナー ガイド
これらのカテゴリは曖昧な場合があり、1 つのドキュメント プロジェクトに複数のドキュメント タイプや機能が含まれることがあります。
詳しくは、Season of Docs 2022 の結果ページをご覧ください。このページには、各組織の元のプロジェクト提案と完全なケーススタディへのリンクが掲載されています。
予算
予算リクエストの平均額は 11,679 ドル、中央値は 12,150 ドルでした。5 つの組織が利用可能な最高額の助成金（15,000 ドル）を申請して受け取り、3 つの組織が最低額（5,000 ～ 7,000 ドル）を申請しました。
指標
ケーススタディで、ドキュメント プロジェクトの成功を測定するために使用した指標について説明しているプロジェクト。
提案された上位の指標は次のとおりです。
提案されたその他の指標は次のとおりです。
- ドキュメントの pull リクエスト/投稿の増加
- ドキュメント ページでの直接的なフィードバックの増加
- ページ滞在時間
- 報告された問題（使用状況の代理変数）
- フォーラムの参加者
- パートナー、ボランティア、統合の数
- 直帰率の低下
- 地域社会での認知度向上。
テクニカル ライティング プロジェクトの完了からケーススタディの提出までの期間が短いため、2022 年の参加者のほとんどは、ケーススタディの提出時に、最初の指標が達成されたかどうかを判断するのに十分なデータを収集できていませんでした。
2023 年にフォローアップ アンケートの回答が届き次第、このレポートを更新し、指標を達成したプロジェクトや指標を改訂したプロジェクトに関する情報を追加します。
詳しくは、Season of Docs 2022 の結果ページをご覧ください。このページには、各組織の元のプロジェクト提案と完全なケーススタディへのリンクが掲載されています。
テクニカル ライターとの連携
Season of Docs プログラムでは、プロジェクトがテクニカル ライターを直接募集、面接、採用、支払うことが求められます。テクニカル ライターは、Season of Docs が管理するディレクトリに GitHub リポジトリから追加できますが、Season of Docs のスタッフがテクニカル ライターを審査したり、推薦したりすることはありません。
オープンソース プロジェクトのテクニカル ライターの採用に関するベスト プラクティス
プロジェクトでは、テクニカル ライターの採用、雇用、協業に関するベスト プラクティスを共有するよう求められました。上位の推奨事項は次のとおりです。
人材サービス
- 面接する候補者の数を減らし、履歴書を確認するだけでなく、ライブの練習セッションを実施する
- プロジェクトの言語やツールに関する熟練度よりも、文書と口頭でのコミュニケーション能力を重視する
- テクニカル ライターがプロジェクトで必要なドメイン知識をどのように習得するかについて、直接質問する
- プロジェクトのミッションに熱意があり、オープンソースの核となる価値観を共有している人は、プロジェクト全体を通してモチベーションを維持できる可能性が高くなります。
- 世界中の応募者を受け入れるようにしてください。多様な視点とバックグラウンドはプロジェクトに役立ちますが、ライターやメンターが競合するタイムゾーンに多すぎると、良好なコミュニケーションを維持するために多くの労力が必要になる可能性があることに注意してください。
採用
- 成果物、支払いスケジュール、特定の時間コミットメントを明確に規定した契約書を使用する
- プロジェクトに不明な点が多い場合は、ドキュメント作成とは別に、調査または研究のマイルストーンを含めます。
調整とコミュニケーション
- 会議のログに決定事項を記録して、プロジェクトに関わる全員がコンテキストと次のステップを把握できるようにする
- 週ごとの電話、毎日のメール、チャット チャネルでのステータス更新など、どのようなコミュニケーションがどのくらいの頻度で必要になるかを明確にする
- 応答性を高め、単に「何」だけでなく「なぜ」も含む明確なフィードバックを提供する
- テクニカル ライターをより広範なコミュニティとつなぎ、コンテキストを提供して、作業を共有する
プロセスとツール
- Season of Docs プログラム終了後も継続し、コミュニティ全体が貢献できるドキュメント プロセスを作成する
- ドキュメントのレビューには、コードレビューと同じくらいの時間がかかり、同じくらい集中的に行われます。十分な時間を確保してください。
一部の推奨事項は、わかりやすくするために編集および簡略化されています。
2021 年のプログラムと同様に、Season of Docs 2022 のテクニカル ライターのほとんどは、協力する組織に直接応募しました。
テクニカル ライターとの連携でよくある問題
2022 年のプログラムでは、テクニカル ライターとの連携に関する問題が報告されたプロジェクトの数が減少しました。病気、フルタイムの仕事への就職、時間の制約を満たせないなどの理由で、テクニカル ライターがプログラムを完了できないことが最大の課題でした。
あるプロジェクトでは、ドキュメント プロジェクトが Google Summer of Code の一環として行われている作業に依存しており、それらの依存関係の管理が難しいと報告されています。別のプロジェクトでは、テクニカル ライターがドキュメント化する必要があるハードウェアが、ライターの国の国防省に没収され、輸入できなくなったという問題が発生しました。
フォローアップ アンケート
2022 年の参加者には、2023 年の 5 月、8 月、11 月に 3 回のフォローアップ アンケートが送信されます。このセクションは、結果が届き次第更新されます。
今後の質問
オープンソースのドキュメントについて学べば学ぶほど、もっと学びたいと思うようになります。
今後のシーズンでは、以下のことを予定しています。
- プロジェクトのメタデータをさらに収集して、プロジェクトの経過期間、コミュニティの規模、言語とドキュメントのニーズの相関関係を調べます
- ドキュメント プロジェクトを分析して、共有可能なテンプレートに一般化できるかどうかを確認する
- オープンソース プロジェクトでテクニカル ライターの面接を行うためのルーブリックを作成する
調査したい質問はたくさんありますが、Season of Docs に参加するオープンソース プロジェクトの管理者とメンテナーの時間を尊重したいとも考えています。このプログラムの最優先事項は、ドキュメントを使用してプロジェクトの問題解決をサポートすることです。