現在のフェーズ:
2019 シーズン オブ ドキュメント プログラムは 2020 年 3 月 6 日に終了しました。タイムラインをご覧ください。
このページには、テクニカル ライター向けのガイドラインが記載されています。今年の Google ドキュメント シーズンの作業を終えた後にプロジェクト レポートを作成する方法を紹介します。
プロジェクト レポートを提出する
プロジェクトの最終処理フェーズが始まると、テクニカル ライター ガイドのプロジェクトの最終処理のセクションで利用可能になるフォームに記入して、プロジェクト レポートを送信できるようになります。
プロジェクト レポートに含める情報
このセクションでは、プロジェクト レポートで指定できる情報の種類について説明します。プロジェクト レポートのフォームには、自由形式の質問と多肢選択式の質問が含まれます。
提出物にリンクする
これまでの取り組みの説明へのリンクを提供します。
リンク先には、行った作業の簡単な説明、オープンソース プロジェクトがリポジトリにマージしたドキュメント、プロジェクトの現状の概要、課題と教訓の一覧が記載されているドキュメントが必要です。
このリンクは、ウェブサイトで公開される Google ドキュメントのシーズンの検索結果に表示されます。 公開された結果により、プログラムで完了した作業が示されます。公開された結果は、履歴書の一部として自分の作品を振り返るための優れた手段でもあります。
プロジェクト レポートを提出する前に、リンクをメンターと共有して審査を依頼してください。
プロジェクト レポートの要件
次の点を考慮してください。
- リンク先のコンテンツでは、Google ドキュメントのシーズン中に作成したドキュメント、つまり変更したドキュメントや新たに作成したドキュメントを簡単に識別できるようにする必要があります。
- 作業は安定した場所に置く必要があります。送信後に URL を変更することはできません。
リンクのターゲットにある（またはリンクのターゲットから参照されている）コンテンツを他のユーザーが使用できるようにする必要があります。
- 作業が 100% 完了していれば、他のユーザーもその課題を使用できます。
- 作業が 100% 完了していない場合は、残りの作業を明確にする必要があります。
仕事の説明のわかりやすい例
これらすべて（またはいずれか）を行う必要はありませんが、次の方法で要件を満たすことができます。
ブログ投稿またはウェブページ、または公開 GitHub gist を作成し、作業内容の説明、commit とリポジトリへのリンクを記載します。プロジェクトに行う作業が残っている場合は、その作業についての説明を含めます。ハイライトや難しい課題を共有することもできます
これは、多くの情報を簡単に含めることができる最適な方法です。自分の作業がはっきりと表示されるため、他の人が自分の投稿を利用し、理解しやすくなります。
GitHub を使用していて、すべての作業が 1 つの pull リクエストでカバーされている場合は、このリンクを使用できます。
- pull リクエストの説明が詳細に記述されていることを確認します。
- 作品が「ドキュメント」シーズン向けであることを説明に明記するようにします。
- ドキュメント シーズンの終了後に pull リクエストにさらに作業が必要な場合は、ドキュメントの最後のシーズンにそのことを明記してください。
- この方法でプロジェクト レポートを提供する方法には、変更ログ、commit のリスト、レビュー コメントがすべて 1 か所にまとめられるというメリットがあります。
GitHub リポジトリが「ドキュメントのシーズン」を単一の目的に使用する場合は、作業の詳細を含む README ファイルを追加してください。
Google ドライブに一般公開フォルダを作成し、作成したすべてのパッチを含めます。
Google スプレッドシートで一般公開のスプレッドシートを作成し、すべての commit を一覧表示する。
公開 Issue Tracker の 1 つの問題にリンクします。その際、自身の作業とその他の適切な内容への明確な参照が記載されます。この問題により、行ったすべての作業が追跡されるはずです。問題にすべての commit が一覧表示されているか、または別の方法で commit を簡単に見つけられるようにします。
変更の統合またはコンテキスト差分にリンクします。他の人の役に立つように、技術的なライティング プロジェクトの名前とデベロッパー名を記載したヘッダーを含めるようにしてください。
仕事の説明の悪い例
次のことはしないでください。
- プロジェクト全体または作業ディレクトリを含む tarball または zip ファイルにリンクします。
- プロジェクトのプライマリ ソース リポジトリの先頭へのリンク。たとえば、cpython を使用している場合、こちらのリンク（https://github.com/python/cpython）は役に立ちません。
- プロジェクトのソース リポジトリのクローンにリンクします。自分の作品が他の人の作品と混在しているため、変更内容を確認するのが難しくなります。
- 「ドキュメント シーズン」のウェブサイトでプロジェクトの説明へのリンク。
メンター向け
テクニカル ライターが適切なプロジェクト レポートを作成するのをサポートしてください。これは、テクニカル ライターの作業に対する独自の評価を作成する前に、行うことが重要です。
以下を確認します。
- 提出物は上記の要件を満たしている必要があります。
- 提出物には、実施した作業の説明、満たした要件、具体的な決定事項の理由を含める必要があります。
「ドキュメント シーズン」の目的は、テクニカル ライターが大量のドキュメントを作成することではありません。作業がホスティングするオープンソース プロジェクトに役立つ可能性があることが重要です。