Season of Docs は、Google オープンソース プログラム オフィスが管理する持続可能性プログラムです。Season of Docs の目標は次のとおりです。
- オープンソース プロジェクトをサポートし、ドキュメントを使用してプロジェクトの問題を解決する
- 技術ライターにオープンソースの経験を積む機会を提供する
- オープンソース、ドキュメント、技術的な文章の認知度を高める
- オープンソースのドキュメントで効果的な指標に関する情報を収集して共有する
Season of Docs について詳しくは、プログラムのウェブサイトをご覧ください。
2022 年のプログラムの概要
Season of Docs の仕組み
Season of Docs では、組織はプロジェクトの提案書を送信して申し込むことができます。プロジェクトの提案書には、以下が含まれます。
- 組織に関する情報
- プロジェクトで発生している問題の説明
- プロジェクトでドキュメントを使用して問題を解決する方法
- プロジェクトでドキュメントの効果を測定する方法（指標）
- 作業のタイムライン
- プロジェクトの予算
- 組織が同様のプログラムで得た経験など、ドキュメント シーズン管理者がプロジェクトと問題を理解するのに役立つ追加情報
プログラムに承認されると、組織は独自の技術ライターを直接募集して雇用します。Season of Docs は Open Collective を使用して組織に資金を提供し、組織は Open Collective を通じて技術ライターに支払います。プロジェクトの予算と支払いは透明性があります。予算は、Season of Docs のサイトで入手できる組織のプロジェクトの提案に含まれ、支払いは Season of Docs Open Collective アカウントに表示されます。
組織は、ケーススタディ レポートを提出すると、プログラムを正常に完了したものとみなされます。また、プログラム期間中は毎月の評価を、プログラム終了後の 1 年間は 4 半期に 3 回フォローアップ アンケートを実施していただく必要があります。
2022 年のハイライト
「新しいドキュメントが公開された後、Casbin と Casdoor への 1 日あたりのアクセス数はほぼ 2 倍になり、離脱率は約 30% 減少しました。」- Casbin
「このプロジェクトの成果として、[技術ライター] がコミュニティのリーダーシップ ロールに成長していく様子を見守ることができたことです。両方のコントリビューターは、現在、ワーキング グループとコミュニティ ミーティングをリードし、プロジェクトの設計とメンテナンスに貢献しています。」 - moja-global
「[GSoD] は、優秀な技術ライターを 2 人採用するのに役立ちました。これは通常の設定では非常に困難です。この 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 年のケーススタディで最も言及されたドキュメント タイプは、方法に関するドキュメントでした。
ケーススタディで言及されているその他のドキュメントの種類には、次のようなものがあります。
- クイックスタート
- 用語集
- よくある質問
- ナレッジベース
- コンポーネント
- ブログ/ソーシャル メディアのコンテンツ
- メンテナー ガイド
これらのカテゴリの中には曖昧なものもあり、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 プログラムでは、プロジェクトが技術ライターの募集、面接、採用、支払いを直接行うことが求められます。テクニカル ライターは、GitHub リポジトリにある Season of Docs が管理するディレクトリに自分自身を追加できますが、Season of Docs のスタッフはテクニカル ライターを審査したり、推奨したりしません。
オープンソース プロジェクト向けの技術ライターの採用に関するベスト プラクティス
プロジェクトには、技術ライターの募集、採用、連携に関するベスト プラクティスを共有するよう依頼しました。主な推奨事項は次のとおりです。
人材サービス
- 履歴書を確認するだけでなく、面接する候補者を減らし、ライブの演習セッションを使用する
- プロジェクトの言語やツールの習熟度よりも、文書および口頭でのコミュニケーション能力を重視する
- プロジェクトの作業に必要なドメイン知識を技術ライターがどのように習得するかについて、直接質問します。
- プロジェクトのミッションに熱心で、オープンソースのコアバリューを共有している人は、プロジェクト全体を通してモチベーションを維持する可能性が高くなります。
- さまざまな視点やバックグラウンドを持つ人材はプロジェクトに役立つため、世界中の応募者を歓迎してください。ただし、ライターやメンターがあまりにも多くの異なるタイムゾーンに分散していると、良好なコミュニケーションを維持するために多くの余分な労力が必要になる可能性があります。
採用
- 成果物、支払いスケジュール、具体的な時間的コミットメントを明記した契約を使用します。
- プロジェクトに不明な点が多い場合は、ドキュメント作成とは別に、検出または調査のマイルストーンを含めます。
調整とコミュニケーション
- 意思決定を記録した会議ログを保持し、プロジェクトに携わるすべての人がコンテキストと次のステップを簡単に把握できるようにする
- 週ごとの通話、毎日のメール、チャット チャネルでのステータス更新など、どのようなコミュニケーションが期待され、どのくらいの頻度で行われるかを明確にします。
- 迅速に対応し、明確なフィードバックを提供します。フィードバックには「何が」だけでなく「なぜ」も含めます。
- 技術ライターを幅広いコミュニティとつなげて、コンテキストを提供し、作業を共有する
プロセスとツール
- ドキュメント シーズン プログラムを超えて継続し、コミュニティ全体が貢献できるドキュメント作成プロセスを作成します。
- ドキュメントのレビューは、コードのレビューと同様に、少なくとも同じ時間と集中力を必要とします。十分な時間を確保してください。
一部の推奨事項は、わかりやすくするために編集され、要約されています。
2021 年のプログラムと同様に、Season of Docs 2022 の技術ライターのほとんどは、提携先の組織に直接応募しました。
技術ライターとの連携に関する一般的な問題
2022 年のプログラムでは、テクニカル ライターとの連携に関する問題を報告したプロジェクトは減少しました。病気、フルタイムの仕事、時間の確保ができなかったことなどにより、技術ライターがプログラムを完了できなかったことが最大の問題でした。
1 件のプロジェクトでは、ドキュメント プロジェクトが Google Summer of Code の一環として行われる作業に依存しており、これらの依存関係を管理するのが難しいと報告されています。別のプロジェクトでは、技術ライターがドキュメント化するために必要なハードウェアがライターの国の国防省によって没収され、輸入できなくなったため、困難に直面しました。
フォローアップ アンケート
2022 年の参加者には、2023 年 5 月、8 月、11 月の 3 回にわたってフォローアップ アンケートが送信されます。結果が判明次第、このセクションを更新します。
今後の質問
いつものように、オープンソースのドキュメントについて学ぶほど、学びたいことが増えてきます。
今後のシーズンでは、以下の点について改善していく予定です。
- プロジェクトのメタデータをさらに収集して、プロジェクトの年齢、コミュニティの規模、言語とドキュメントのニーズとの関連性を探る
- ドキュメント プロジェクトを分析して、共有可能なテンプレートとして一般化できるかどうかを確認する
- オープンソース プロジェクトの技術ライターへの面接用評価基準を作成する
調査したい質問はたくさんありますが、ドキュメント シーズンに参加しているオープンソース プロジェクトの管理者とメンテナンス担当者の時間を尊重することも重要です。このプログラムの最優先事項は、ドキュメントに関する問題の解決をプロジェクトがサポートできるようにすることです。