現在のフェーズ:
2021 年シーズン オブ ドキュメント プログラムは 2021 年 12 月 14 日に終了しました。タイムラインをご覧ください。
ドキュメントのシーズンについて
Season of Docs は、Google オープンソース プログラム オフィスが管理するサステナビリティ プログラムです。「ドキュメント シーズン」の目標は次のとおりです。
- ドキュメントを使用してオープンソース プロジェクトをサポートし、プロジェクトの問題を解決します。
- テクニカル ライターにオープンソースでの経験を積む機会を提供する
- オープンソース、ドキュメント、テクニカル ライティングの認知度を高める
- 効果的な指標に関する情報を集めてオープンソースのドキュメントで共有
「ドキュメントのシーズン」について詳しくは、本プログラムのウェブサイトをご覧ください。
2021 年のプログラム概要
2021 年のプログラムの変更点
2019 年と 2020 年には、組織とテクニカル ライターがそれぞれ Season of Docs プログラムに個別に応募し、シーズン シーズン プログラム管理者によってテクニカル ライターと組織のマッチングが行われました。組織は、テクニカル ライターと連携するためのメンターを派遣し、テクニカル ライターは勤務地に応じた給与を受け取ります。このプログラムでは、テクニカル ライター、メンター、組織管理者が、プログラムへの参加に満足しているかどうかを測定しましたが、ドキュメントの成果は測定しませんでした。
2021 年、Season of Docs チームはプログラムに大幅な変更を加え、ドキュメントの成果の測定と、組織とテクニカル ライターの柔軟性の向上に重点を移しました。
- 組織がプロジェクトの提案(予算、提案される指標を含む)を適用
- テクニカル ライターは、組織とのマッチングを目的とした Google からの申請ではなく、承認を受けた組織に直接申請する
- 承認された組織は Open Collective を介して資金援助を受けており、これまではテクニカル ライターに支払っていました。
- テクニカル ライターの報酬は組織によって設定済み
- 各組織は最終評価とケーススタディを提出し、フォローアップ アンケートに回答
2021 年の一般的な調査結果
組織
- 2021 年のプログラムの変更により、応募した組織は減少しましたが(2021 年と比べて 30% 少ない組織で応募した)、2021 年の組織管理者のプログラムに対する満足度は、2020 年の組織の管理者のプログラムに対する満足度がわずかに高まりました(93% 対 91%)
問題、ドキュメント タイプ、指標
- ほとんどのプロジェクトは、(問題や質問を減らすことで)メンテナンス担当者の負担を軽減したり、(プロジェクト ユーザーまたはコントリビューターによる)プロジェクト参加を増やしたりするためのドキュメントの作成に重点を置いています。
- 承認を受けた組織の 50% がチュートリアルやハウツー コンテンツを制作。
- 承認された組織の 50% 以上が、現在のドキュメントが不足している、整理されていない、または古くなっていると考えています。
- 一般的に、プロジェクトでは、やり取りを通じてドキュメントの効果を測定することが望まれます。特に、発生する問題が少なく、ドキュメントの訪問者やプロジェクトへの参加が増えること。
- 2022 年 11 月時点で、30 件中 25 件のプロジェクトが対応しています。
- 18 件のプロジェクトが元の指標を満たしたと回答
- 5 件のプロジェクトが指標の修正を達成
- 2 件のプロジェクトでは、まだお知らせできないと回答しています
プログラムへの参加
- テクニカル ライターの採用、採用、支払いは、組織管理者にとってこのプログラムで最も難しかった部分でした。
- 2022 年 11 月時点で、30 社中 24 社が回答しています。
- 18 の組織が、引き続きコントリビューターとして、または質問に回答するリソースとして、シーズンの Google ドキュメント テクニカル ライターと作業を続けている。
- 4 社の組織が有償で Season of Docs のテクニカル ライターと連携
- 18 の組織が、引き続きコントリビューターとして、または質問に回答するリソースとして、シーズンの Google ドキュメント テクニカル ライターと作業を続けている。
2021 年のハイライト
- 複数のプロジェクトから、テクニカル ライターが「ドキュメント シーズン」プログラム終了後もプロジェクトを継続するつもりがあると指摘されました
- Metanorma は有資格のテクニカル ライターが多数応募したため、プログラム期間中に Google ドキュメント対応ライターのシーズンと共同で作業するライターを 1 人雇用するために、マッチングの資金を見つけました。
- Moja Global は、コミュニティがドキュメント作成に非常に熱心に取り組んでいることを知り、より多くの貢献者がプロジェクト ドキュメントに参加できるように、新しい Documentation Working Group を設立したことを発見しました。
2021 年の概要データ
2021 年には、82 の団体からご応募いただき、30 のオープンソース団体がプログラムに承認されました。(選択基準については、アプリケーションの作成ガイドをご覧ください)。参加組織の一覧は、ドキュメント シーズンのウェブサイトで確認できます。参加承認を受けた 30 の組織はすべて、最終の事例紹介レポートを提出し、2021 年のプログラムへの参加を終了しました。
組織について
「ドキュメント 2021」シーズンに参加した組織は、多様なオープンソース プロジェクトに参加しました。2021 年のコホートには、
- 大規模言語プロジェクト(Julia、Perl、R など)
- 教育、気候変動、フィンテック、医療、図書館サービス、機械学習、質量分析、公共契約、ロボット工学のプロジェクト
- カオス エンジニアリング ツール、ファザー、chatbot SDK、ソフトウェア構成分析パイプライン、パフォーマンス モニタリング ツール、ビジュアル プログラミング ツールなど、デベロッパー向けのプロジェクト
- Redocly、Metanorma などのドキュメント化ツールのドキュメント プロジェクト
Python エコシステム プロジェクトが最大のサブカテゴリでした。2021 年のコホートには、ArviZ、NumPy、MicroPython、PyMC3、PyTorch-Ignite、SymPy が含まれていました。
Google はプロジェクトに関するメタデータ(設立日、コントリビューターの地理的分布、コントリビューター数、ユーザーベースの規模など)を収集していません。
Google は、どのオープンソース ライセンスを使用したかを示すようプロジェクトに依頼しました。
2021 年の組織によって報告されたドキュメントの問題は、オープンソース プロジェクトと技術ドキュメント全般の両方で非常に一般的な問題です。
2021 年のプログラムで組織が解決したいと考えていた主な問題には、次のようなものがあります。
なお、ドキュメントに関する問題は組織から複数報告される場合があります。詳細については、ドキュメント シーズン 2021 の結果ページで、各組織の事例紹介全体へのリンクをご覧ください。
作成されるドキュメントの種類
2021 年のケーススタディで最も多かったドキュメントの種類はチュートリアルでした。
ケーススタディで取り上げたその他のドキュメント タイプには、Docs-as-Code パイプライン、図、用語集、スタイルガイド、よくある質問、国際化、Codelab、コンテンツ モデル、モジュール、コンセプト ドキュメント、エラー メッセージ、ユーザー調査、Readme、ナレッジベースなどがあります。
これらのカテゴリの中には不明瞭なものもあり、1 つのドキュメント プロジェクトに複数のドキュメント タイプや機能が含まれていることもあります。
ドキュメントの種類を計画する際のガイドとして、Diátaxis フレームワークを使用して特に参照しているプロジェクトが複数あります。
詳細については、ドキュメント シーズン 2021 の結果ページで、各組織の事例紹介全体へのリンクをご覧ください。
予算
2021 年の予算リクエストの平均額は 10,200 ドル、中央値は 10,000 ドルでした。上限額(15,000 ドル)の資金援助をリクエストして受けたのは 3 団体、最低額(5,000 ドル)の資金援助をリクエストした団体は 3 社のみです。
指標
ケーススタディでまとめられたプロジェクト - ドキュメント プロジェクトの成功を測定するために使用していた指標。
特に提案された指標は次のとおりです。
提案されたその他の指標には、GitHub の星、ページ滞在時間、メーリング リスト コンバージョン、定性的ユーザーテスト、フォーラム参加者数、パートナー/ボランティア/統合の数などがあります。
テクニカル ライティング プロジェクトの完了からケーススタディの提出までの期間が短いため、2021 年のコホートのほとんどは、初期指標を満たしているかどうかを判断するのに十分なデータを収集できていませんでした。
詳細については、ドキュメント シーズン 2021 の結果ページで、各組織の事例紹介全体へのリンクをご覧ください。
テクニカル ライターとの連携
2021 年に実施した Season of Docs プログラムに対する最大の変更点は、プロジェクトとテクニカル ライターの連携に関するものでした。以前のシーズンでは、テクニカル ライターが Google に直接応募し、プログラム管理者とプロジェクトがマッチングされ、Google から直接一定の給与が支払われていました。
2021 年には、テクニカル ライターがプロジェクトに直接応募し、プロジェクトがテクニカル ライターの報酬の予算を設定し、Google ドキュメントの Open Collective Fund のシーズンを通じて支払いが行われました。
2021 年度のプログラムに参加したプロジェクトのほとんどは、テクニカル ライターの採用や採用の経験がほとんど、あるいはまったくありませんでした。また、多くのプロジェクトが、プロセスのこの段階を、さらなるサポートを必要とすると指摘しています。このフィードバックを受け、シーズン オブ ドキュメント チームは、プログラム ガイドにテクニカル ライター契約を作成するためのドキュメントを追加しました。
採用に関する提案
「ドキュメントのシーズン」への参加に興味がある他のプロジェクトについて、推奨事項を作成するよう依頼がありました。採用に関する主な推奨事項は次のとおりです。
- テクニカル ライターの採用資料をできるだけ早く(プログラムへの参加が承認される前でも)共有してください。コミュニティに求人候補を紹介してもらってください。
- プロジェクト チャネル外で広く共有する。インクルーシブな表現を使用し、社会的地位の低い志願者の応募を直接奨励します。
- ドキュメント作成プロセスに不可欠なツールを把握し、それらのツールを使用した経験のあるテクニカル ライターを採用します。
- 成果物とマイルストーン、コミュニケーション チャネルとチェックイン、支払いプロセスとタイミングについて、テクニカル ライターに明確な期待値を設定します。
- コミュニティ メンバーへの投資や、彼らがテクニカル ライターとして成長できるよう、ドキュメント シーズンのテクニカル ライターとしてメンターシップやコーチングを提供することを検討してください。
- テクニカル ライターのオンボーディング、プログラム期間中の質問への回答、サポートの提供に、想定よりも多くの時間を割り当てる。テクニカル ライターが該当プロジェクトの分野での経験がない場合は特に重要である。
- 今後のプロジェクトで使用できるように、採用、採用、オンボーディングのプロセスを文書化します。
(注: テクニカル ライター候補者を採用したケーススタディで示されているプロジェクトがすべてあるわけではありません)。
テクニカル ライターとのやり取りに関する一般的な問題
複数のプロジェクトのテクニカル ライターは、COVID-19(新型コロナウイルス感染症)などの病気のため、あるいはパンデミックに伴う家族の責任のために中退しなければなりませんでした。一部のプロジェクトでは、タイムゾーンの不一致やインターネット接続の問題が関係する通信の問題が報告されています。
複数のプロジェクトが、コミュニティへのオンボーディングやプロジェクトのドキュメント ツールチェーンの設定に伴う困難を過小評価していたことに気づきました。
一部のプロジェクトでは、Open Collective における銀行取引の問題や、ライターの拠点国に支払い制限があるため、テクニカル ライターへの支払いが遅れていました。
Open Collective の料金に関するプログラムのドキュメントが明確ではありませんでした。Google は、プロジェクトへの資金の初回の移転にかかる Open Collective の取引手数料を負担していますが、他の一部の決済チャネルから課される取引手数料(通貨換算手数料など)は負担していませんでした。今後のプログラムのドキュメントで、この点を明確化する予定です。
フォローアップ アンケート
シーズン オブ ドキュメント プログラムの一環として、プロジェクトにはフォローアップ アンケートへの協力をお願いしました。アンケートは 2022 年 5 月、8 月、11 月に 3 回実施されました。
フォローアップ アンケートでは、提案と事例紹介のリンクがまだ有効であることを確認するよう依頼しました。このアンケートには、プロジェクトの成功(ケーススタディで設定した指標によって決まります)や、プロジェクトのテクニカル ライターの継続的な参加と報酬に関する質問も含まれています。
- 「Google ドキュメント シーズン」のテクニカル ライターは現在も連携中ですか?
- テクニカル ライターが引き続きプロジェクトを担当している場合、なんらかの報酬は支払われていますか?
- この時点で、ドキュメント プロジェクトは成功したと感じますか。
今後の質問
今もそうですが、オープンソースのドキュメントについて知識が増えれば増えるほど、学びも増えます。これからのシーズンに、次のことを学びたいと考えています。
- プロジェクト ドメインが doctype 選択または指標の選択に相関しているかどうか
- プロジェクトの完了とテクニカル ライターの定着率に最も効果的なテクニカル ライターの採用とオンボーディングのプラクティスはどれか
- ドキュメントの有効性測定の妥当なタイムライン
調査したい質問はたくさんありますが、Google は、ドキュメント シーズンに参加するオープンソース プロジェクトの管理者やメンテナンス者の時間を尊重したいとも考えています。プログラムの最優先事項は、プロジェクトが文書化して問題を解決できるように支援することです。