このページは Cloud Translation API によって翻訳されました。

ドキュメントのシーズンの事例紹介の例

現在のフェーズ:
2021 年の Season of Docs プログラムは 2021 年 12 月 14 日に終了しました。タイムラインをご覧ください。

この例を参考に、独自のケーススタディレポートを作成してください。

PicklePlus: GloriousPickle コントリビューションツールに関するドキュメント

Organization or Project: Glorious Pickle（組織またはプロジェクトのメインサイトへのリンクはこちら）

組織の説明：GloriousPickle（現在のバージョン 1.2.3、2009 年最初のリリース）は、1 台のキュウリの一人用から容器出荷まで、可能なすべてのピクルス野菜の塩、砂糖、酢、スパイスの完璧な比率を簡単に計算できる MIT ライセンスのライブラリです。

作成者: 省略可: ケーススタディの作成者をリストします。リクエストされた場合はユーザー名を使用します

問題の説明/提案の概要

新しいドキュメントや改善されたドキュメントで解決しようとしていた問題は何ですか？可能であれば、プロジェクトサイトの提案ページへのリンクを記載してください。

GloriousPickle ツールの成分データベースに成分を追加するのは時間がかかり、複雑です。また、このツールには適切なドキュメントがありません。コントリビューターになりたい人の多くは、git の使用や pull リクエストの作成の経験がありません。つまり、GloriousPickle には成分データに重大な欠落があり、ツールの有用性が低下しています。新しい食材を追加するためのドキュメントを改善することで、新しいコントリビューターが参加しやすくなり、より多くのピクルスが作られることを願っています。

プロジェクトの説明

提案書の作成

ドキュメントシーズンの提案はどのようにして生まれましたか？アイデアが決まるまでに、どのようなプロセスを使用しましたか？フィードバックをどのように募集し、取り入れましたか？

GloriousPickle PickleDocs SIG は、Google のオープンソースプログラムオフィスのツイートを通じて、ドキュメントシーズンプログラムについて知りました。SIG は隔週の会議でプログラムについて話し合い、提案書を作成することに同意しました。SIG の 2 人のメンバー（@KimChiCook と @Dillicious）が、次の会議で審査するための提案書の下書きの作成に志願しました。

PickleDocs SIG が提案書の下書きに同意すると、プロジェクト全体にフィードバックを依頼するメールが送信されました。14 人のコミュニティメンバーからフィードバックが寄せられました。その中には、材料追加 API のメンテナーである @GloriousPicklePat も含まれています。@GloriousPicklePat さんは、プログラムの期間中、リソースとしてボランティアとして参加しました。

寄せられたフィードバックについて協議し、取り入れた提案は、GloriousPickle プロジェクト運営委員会に送られ、投票が行われました。GPPSC の 5 人のメンバー全員が、提案書と申請書の提出に賛成票を投じました。また、@VinegarViv は、プログラムへの参加と支払いの管理に必要な Open Collective アカウントの作成を支援することに同意しました。

予算

予算に関する短いセクションを追加します。作業時間をどのように見積もりましたか？想定外の支出はありましたか。結局、資金は助成金よりも少なくなりましたか？Google ドキュメントのシーズン以外で使える資金はありましたか。

GloriousPickle PickleDocs SIG のメンバー 2 人は、テクニカルライターとして活動しています（ヨーロッパに 1 人、アルゼンチンに 1 人）。以前に作成した提案書の下書きと比較して、作業量を見積もったり、類似のプロジェクトの予算を調べたりしました。また、2019 年の PicklePals コンベンションから残った、制限なしのスポンサーシップ資金 1,000 米ドルもプロジェクトに充てられました。

予期せぬ費用として、山火事の影響を受けた地域に住むテクニカルライターが自宅でインターネットにアクセスできなくなったため、Wi-Fi アクセスポイントをレンタルしたことが挙げられます。また、参加者に送付する T シャツも当初予定していたより少なくなったため、バランスが取れました。

また、技術ライターが作成したドキュメントのコピー編集と校正を支援するため、GloriousPickle の投稿者である @Piccalily（かつてピクルス以外の生活でプロのコピーエディタだった）に報酬を支払うことにしました。

参加者

このプロジェクトに携わったメンバー（参加者がリクエストした場合はユーザー名を使用）技術ライターをどのように見つけ、採用しましたか？他のボランティアや有料参加者をどのように見つけましたか？どのような役割を担っていましたか？途中でやめた人はいますか？採用、コミュニケーション、プロジェクト管理について学んだことは何ですか？

このプロジェクトに携わったコアチームは次のとおりです。

@Dillicious、@KimChiCook（PickleDocs SIG）
@Piccalily（校正編集者）
@GherKen、@VinegarViv（管理者向けヘルプ、GPPSC）
@BBChips、@GloriousPicklePat（内容領域の専門家）
Sam Scribe（テクニカルライター）

Sam Scribe は、Season of Docs GitHub リポジトリのリストで見つけました。サム氏は料理雑誌で働いた経験があり、ウェブサイトのドキュメントも作成していたため、その経験がプロジェクトに適していると考えました。Sam は PickleDocs SIG の 2 週間に 1 回のミーティングに参加し、プロジェクトについて話し合いました。その際、いくつかの非常に有益な提案があり、提案書に組み入れました。また、SIG メンバーのネットワークを通じて、他の 2 人の技術ライターにも連絡しましたが、どちらもプログラム期間中は対応できませんでした。

Sam のタイムゾーンは PickleDocs SIG のほとんどのメンバーと数時間しか重複していないため、Sam のタイムゾーンに住み、材料の追加プロセスに精通している Picklers のディスカッションフォーラムにコールを送付した。@BBChips は、Sam の質問に答え、必要に応じて他の専門家を探すことにボランティアとして参加しました。@GloriousPicklePat は、ツールの基盤となるアーキテクチャと API から返される可能性のあるエラーメッセージについて Sam をサポートし、GitHub と git のサポートも提供しました。

残念ながら、番組の途中で @VinegarViv さんが個人的な理由によりプロジェクトから離れざるを得なくなりました。GPPSC メンバーの @GherKen が、管理と支払いに関する質問に対応しました。

質問に見落としができた場合（GloriousPickle は無料の Slack インスタンスを使用し、ディスカッションが急速に進行し、アーカイブ制限の間隔があって会話が失われることもある）、共有ドキュメントに進行中の質問のリストを保持する必要があることを学びました（共有の Google ドキュメントを使用しました）。PickleDocs SIG のメンバーは、各ミーティングの前に確認し、ミーティングが終了する前に回答を確実に得るようにしました。Sam は緊急の質問を @BBChips に直接送信できました。

Sam や Sam と協力して作業できて本当に良かったです。また、GloriousPickle のドキュメントを更新しただけでなく、2 人もピクラーに夢中になりました。

タイムライン

プロジェクトのタイムラインを簡単に示します（プロジェクトが進行中の場合は、終了予定日または中間マイルストーンを示す）。

Season of Docs プログラムの参加組織が発表されるのを待っている間、PickleDocs SIG のメンバーは、Sam に役立つと思われる過去の作業を検索しました。1 か月間かけて、ドキュメントの更新作業が中断された以前の取り組みに関するメモを見つけ、Google OpenDocs リポジトリのドキュメントの成熟度監査資料の一部にも取り組みました。

2021 年の Google ドキュメントのシーズンに当選したという良い知らせを受けて、Sam と PickleDocs SIG が会い、大まかなスケジュールを立てました。

ステージ	完了者
ドキュメント監査を確認する	5 月 7 日
摩擦ログの 3 つのユースケース	5 月 14 日
@GloriousPicklePat と @BBChips と一緒に摩擦ログを確認し、質問に回答する	5 月 28 日
更新されたドキュメントのユースケース 1 の最初の下書き	6 月 25 日
ユースケース 1 のドラフトを @GloriousPicklePat と @KimChiCook がレビュー	7 月 2 日
更新されたドキュメントのユースケース 2 の最初の下書き	7 月 2 日
ユースケース 2 のドラフトを @GloriousPicklePat と @Dillicious がレビュー	7 月 9 日
更新されたドキュメントのユースケース 3 の最初の下書き	7 月 9 日
ユースケース 3 の下書きを @Dillicious と @KimChiCook が確認しました	7 月 16 日
すべてのユースケースですべてのクエリに回答	7 月 30 日
PickleDocs SIG のほとんどのメンバーが 8 月 1 日から 20 日まで休暇中でした	--
コミュニティで新しいドキュメントのテストを開始（ドキュメントが GloriousPickle サイトに下書きとして公開されている）	8 月 21 日
テストのフィードバックを反映	9 月 10 日
新しいドキュメントの校正と校閲	9 月 17 日
ドキュメントの下書きステータスを削除し、ドキュメントを正式にリリースしました	9 月 28 日
作成したドキュメントを更新するプロセス	11 月 1 日
このケーススタディは	11 月 8 日
事例紹介の提出	11 月 16 日

提案の予算では、テクニカルライターが週に 10 ～ 15 時間をプロジェクトの作業に費やすと見積もっていました。Sam は費やした時間を記録しており、週平均は 11.5 時間でした。

結果

作成、更新、または変更された内容公開されているドキュメントへのリンク（該当する場合）提案書に記載されている成果物のうち、作成されなかったものはありますか？それらもすべてご記入ください。

3 つの主要なユースケースが、ユーザー向けの詳細なガイドとともに文書化されています。

GloriousPickle に新しい材料を追加する方法

GloriousPickle にバリエーションの材料を追加する方法

GloriousPickle で材料を更新または修正する方法

これらのガイドには、投稿を容易にするための新しい pull リクエストのテンプレートも含まれています。

また、プロジェクト期間中に、学んだ用語の簡単な Pickle 用語集を作成しました。この用語集は GloriousPickle プロジェクトサイトにも公開されています。

これらのユーザー向けハウツーガイドを更新するための手順をプロジェクトのウィキに追加しました。

GitHub を初めて使用するコントリビューター向けに、プロセスとツールの使用を支援するチェックシートの作成を予定していましたが、利用可能なリソースを確認した結果、別のプロジェクトのチェックシートをフォークすることにしました。

指標

プロジェクトの成功を測定するために、どのような指標を選択しましたか。これらの指標を収集できましたか？指標は、プロジェクトに期待される成果との相関関係を示していますか？提案時から指標は変わりましたか？

提案では、次の 2 つの指標を提案しました。

成分関連の pull リクエストの数
新しいコントリビューターからの pull リクエストの数

9 月（ドラフトドキュメントの公開から最初の 1 か月間）は、成分関連のプルリクエストが 5% 増加しました（8 月の 20 件から 9 月の 21 件）。また、3 人の新規コントリビューターが合計 4 件のプルリクエストを送信しました（8 月の 2 人の新規コントリビューターが送信した 2 件のプルリクエストと比較して）。これらの指標は毎月追跡される予定です。

1 月 1 日からは、ドキュメントが公開されてから四半期ごとに、全体で 3 回以上貢献したコントリビューターの数も追跡されます。

新しいドキュメントにより、新しいコントリビューターが GloriousPickle の成分データベースに追加できるようになったという報告が寄せられています。ある新しいコントリビューターは、以前に試したことがあったものの、プロセスを理解していなかったため更新を完了できなかったと PR のコメントで述べています。

分析

上手くいった点想定外だった点はどのような点ですか？どのような障害や挫折に直面しましたか？プロジェクトは成功していると思いますか？その理由をお聞かせください。（判断するには時期尚早の場合は、プロジェクトの成功を判断できる時期を説明してください）。

Google は、ドキュメントシーズンプロジェクトの成果に非常に満足しており、成功と考えています。新しいドキュメントは明確で有用であり、すでに、コンポーネント関連のプルリクエスト数と、新しいコントリビューターからのプルリクエスト数の増加が見られます。

また、GloriousPickle コミュニティのほぼ全員が、元の提案に対するフィードバックの提供や、下書き版の新しいドキュメントのテストを通じて、参加してくれたことも喜ばしいことでした。

予想外の障害がいくつかありましたが、サムさんが住む州の山火事でインターネットが停止した以外に被害がなかったことを心から感謝しています。また、このプロジェクトから @VinegarViv が亡くなってしまい、大変残念に思います。彼女とご家族のご健闘をお祈りし、近日中にまたお会いできることを願っております。

Sam がドキュメントの作成を開始するまで、私たちが気づかなかったことの 1 つは、pickle に関する経験のない人にはなじみのない pickle 関連の用語や頭字語がいかに多いかということでした。ただし、Sam は、不明な用語をすべてリストにまとめ、独自の調査やコミュニティメンバーに説明や参考資料を求めて、それらを定義しました。このピクルス用語集は、今後、より多くの人々をピクルスコミュニティに迎え入れる際に大いに役立つでしょう。

概要

プロジェクトの経験を 2 ～ 4 つの段落で要約してください。学んだことと、将来どのように変えていきたいかを強調します。ドキュメントに関する同様の問題を解決しようとしている他のプロジェクトに、どのようなアドバイスを送りますか？

一言で言えば、ピクルスエクスペリエンスは最高でした。文書化の成果物が達成され、指標は目標に沿っているようです。

このプロジェクトの成功の大きな要因は、技術ライターの Sam Scribe と協力できたことです。[これは私が書いたものではありません - Sam] Sam はピクルスに関するバックグラウンドや GitHub の経験はありませんでしたが、経験豊富な技術ライターとして、新しい分野に飛び込んで質問したり、調査したりすることに抵抗はありませんでした。Sam は、プロジェクトツール（Google ではカンバンボードを使用して作業を追跡しています）だけでなく、ピクルスに関するジョークもすぐに覚えました。Sam がピクルスバグを捕捉し、コミュニティで「ボトル詰め」できたことを大変うれしく思います。

他のプロジェクトには、次のことをおすすめします。

提案は小さく、管理しやすいものにします。（当初は、産業用バッチ漬け込み機械で推定ツールを使用するドキュメントを提案書に含める予定でしたが、漬け込み機械のオープンソース化に深く関わっているコミュニティメンバーの 1 人がプログラム中に博士論文を執筆する予定だったため、除外しました）。結局、Sam を無理やり続けられるほどの仕事ができました！
技術ライターを探す際には、ネットワークを活用しましょう。コミュニティ内の全員におすすめを尋ねます。Sam は GitHub の Season of Docs GitHub で見かけましたが、応募期間中に複数の人たちと話していたので、自信を持って仕事に取り組めました。
技術ライターをコミュニティに迎え入れましょう。Sam は、GloriousPicklers の熱心な姿勢のおかげで、質問しやすかったと語っています。
テクニカルライターがオープンソースのスキルを習得できるよう支援します。Sam は Git を使用したことがありませんでしたが、いくつかのチュートリアルを経てすぐに使いこなせるようになりました。最初、サムはコミュニティからどれくらいのフィードバックが得られるか、そのフィードバックをどのように取り入れたらよいか心配していましたが、Google のコミュニティの「大まかなコンセンサス」モデル（「コンセンサスはすべての問題に対処したときに達成されるが、必ずしも対応する必要はない」）により、サムは技術的な文章作成の専門知識を使って批判に対処することに自信を持つことができました。

付録

リンク先として他の資料がある場合（たとえば、共有する技術ライターとの契約書、ドキュメントプロジェクトのテンプレート、その他の公開ドキュメントリソースを作成した場合は、ここでリストしてリンクできます）。付録には、使用したドキュメントツールやリソースへのリンクを記載したり、上記のセクションに収まらない謝辞や謝意を記載したりするのにも適しています。

謝辞

弊社チームは、以下の方々や事柄に感謝いたします。

@Dillicious はパートナーとローファイヒップホップラジオに感謝しています
@KimChiCook はピクルスの作り方を教えてくれた 할머니 に感謝しています
@Piccalily は Chicago Manual of Style Online に感謝しています
@GherKen は、作ったピクルルをすべて食べてくれた 3 人の子供に感謝しています
@VinegarViv は、退任に際してチームの皆様にご協力いただいたことに感謝しています
@BBChips は、ピクルス以外の最高の食べ物である Tunnock's Caramel Wafers に感謝しています
@GloriousPicklePat は、このプロジェクトを引き受けてくれた PickleDocs SIG に感謝します
Sam Scribe は、GloriousPickle コミュニティ全体に感謝の意を表します。特に、2021 年夏の瓶不足の際に、おいしいピクルスの道を歩み始めた Sam に、密閉瓶を送ってくれた Pickler の皆様に感謝します。