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