このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- Kolibri
- テクニカル ライター:
- Danielle V
- プロジェクト名:
- Kolibri コンテンツ ワークフロー
- プロジェクトの長さ:
- 長期実行（5 か月）
プロジェクトの説明
以下の提案は、調査を行い、Kolibri のメンターと対話することにより作成されました。メンターとの会話から、後述するユーザー ペルソナを作成できました。また、ユーザーがニーズに応じてどのチュートリアルを表示するかを選択できるように、チュートリアル リポジトリ/ランディング ページに関するアイデアも出てきました。
概要
この提案では、ユーザーがコンテンツをパソコンから Kolibri Studio にインポートし、Kolibri Studio から Kolibri にインポートする際に利用できるさまざまなユーザー ジャーニーをガイドするソリューションを提示します。チュートリアルの中央リポジトリを作成することを提案します。ユーザーはランディング ページからこれらのチュートリアルにアクセスします。ランディング ページには、各ワークフローのチュートリアルへのリンクを含む表が表示され、チュートリアルが役立つユーザーのタイプが示されます。これにより、チュートリアルはユーザーのニーズや能力に合わせてよりパーソナライズされます。ワークフロー（INSTALL-IMPORT など）は複数のレッスンで説明されます。各レッスンには動画が含まれています。動画では、ワークフローの一部を紹介し、これらのワークフローが Kolibri アプリケーションをどのように接続するかに関する個々のコンセプトを示します。
主な目標
ユーザーがニーズに最適なワークフローを判断するのに役立つチュートリアルのランディング ページを作成します。このランディング ページは Read the Docs プラットフォームでホストされます。
各ワークフローのコンポーネントごとにレッスンを作成し、難しいレッスンを演習で補完します。
ワークフローごとにインタラクティブな動画を作成します。
プロジェクト ツール
作業は画面キャスト ソフトウェアを使用して行われます。Camtasia の使用経験がありますが、費用が抑えられるソフトウェアやフリーウェアも使用しています。こちらのリンク先のサンプル動画（https://youtu.be/DkMP_VdGslU）は、Blueberry Software の Flashback を使用して制作されており、現在ライセンスを所有しています。YouTube を使用して字幕を作成します。チュートリアル ページは、Kolibri の Read the Docs サイトでホストされます。下書きは Google ドキュメントで作成します。最終的な成果物としてテキスト ファイルを Markdown または reStructuredText に変換するサポートも可能です。
タイムライン
このプロジェクトは、長期プロジェクトのガイドラインに沿って実施されます（2019 年 9 月 2 日～ 2020 年 2 月 28 日、合計 26 週間）。以下の目標を達成するために、週に 10 時間ほど費やす予定です。これらの目標に加え、必要に応じてこの期間中、メンターのミーティングやコミュニケーションにも参加します。メンターと協力して、最適な日時を決定いたします。タイムラインは通常、4 週間のブロックに分かれており、複数の動画、チュートリアル ページ、演習が作成されます。
第 1 週と第 2 週
目標:
- 情報にアクセスするために必要なウェブサイトやアカウントを使用して、個人のデバイスを設定します。
- ランディング ページの構造と詳細なワイヤーフレームの作成を開始します。
- 動画のスタイルについてメンターと話し合い、動画のオープニング画面のテンプレート、タイトル画面と終了画面のフィラー ミュージック、追加する必要がある情報を作成します。
- 現在のドキュメントとドキュメント構造を確認して、追加のリソースやチュートリアルの参照に使用するリンクを抽出します。
第 3 週～第 6 週（レベル 1 - 初級者向けチュートリアル）
目標:
- インストール - インポート/レベル 1 のワークフローの最初のコンテンツとレッスンを作成します。ダウンロード、インストール、構成、インポートのプロセスを説明する動画を作成します。INSTALL-IMPORT 関数は他の多くのワークフローの基礎であり、最もよく使用されるため、これらのチュートリアルとレッスンの完成に多くの時間を費やすことになります。
- 場所のタイプ IMPORT に重点を置き、ユーザーがどこからランディング ページのコンテンツ（Kolibri Studio に存在する公開チャンネル）を取得できるかを示すグラフィックを作成します。
- インストールとインポート（チャンネルの更新）の拡大に向けて、追加の動画とコンテンツを作成します。これらの拡張は、追加リソースや既存のドキュメントへのリンクの形で提供されることもあります。
- あらゆる動画の字幕を作成する。
- 動画を「テスト」し、利用可能なリソースからユーザビリティに関するフィードバックを依頼します。これには、動画用のテンプレートの見直しや、今後の動画用のテンプレートの強化が含まれます。
第 7 ～ 10 週（レベル 2 - コンテンツ アップロード担当者）
目標:
- Studio アップロード ペルソナ向けのレッスンとワークフロー動画に焦点を当てます。
- UPLOAD-PUBLISH-IMPORT の完全なドキュメントとレッスン。
- 任意の動画の字幕を作成します。
Weeks Eleven Through Fourteen（レベル 3 - コンテンツ「リミキサー」と編集者）
目標:
- 次のワークフローに焦点を当てて、チュートリアル/レッスン コンテンツを作成します。アップロード - 編集 - 公開 - 更新、編集 - 公開 - 更新。
- 動画の字幕を作成します。
第 15 週～第 18 週
目標:
- この提案の調査中に伝えたように、Ricecooker を含むワークフローは優先度が低く（CHEFDEV タイプ）、タイミングとスケジュールにもよりますが、ここでは概要的なチュートリアルを作成して、Ricecourseer の既存のドキュメントを参照することもできます。
第 19 週～第 22 週
目標:
- この時点でギャップがないか評価し、すべてのチュートリアルの現在の流れをテストします。
- ランディング ページの最終調整を行い、動画をリンクし始めます。
- メンターと話し合うように、Google ドキュメントで作成したページの下書きを Markdown または reStructuredText に変換する方法を学びます。
第 23 週～第 25 週
目標:
- 時間に応じて、優先度の低い上級向けチュートリアルの最終的な作業を完了します。
- ドキュメント ページの編集、ファイル テスト、文法/スペルのチェックなどを読む。
- 動画内や他のページにあるリンクの QA。
第 26 週
長期プロジェクトの最終週。メンターと協力してプロジェクトの成果物をまとめ、最終的に必要な Google ドキュメントを完成させます。
チュートリアル コンポーネント
チュートリアルのランディング ページ
ユーザーは、Kolibri の Read the Docs サイトのチュートリアル ランディング ページにアクセスします。このページには、コンテンツ ワークフローに提供されているさまざまなチュートリアルの概要が記載されています。このページでは、Kolibri エコシステムの概要と、さまざまなワークフローのグラフィック表示について説明します。これにより、ユーザーは、技術的な面と組織のカリキュラムの両方のニーズに適した種類のワークフローを確認できます。ユーザーは、Kolibri と Kolibri Studio で利用できるオプションをより深く理解できるようになります。
チュートリアルとレッスンのページ
各チュートリアルのホームページでは、チュートリアルの概要（複数のレッスンから成る）に続いて、ユーザー向けの目標を記載しています。チュートリアルはワークフロー全体を説明したもので、個別のレッスンで構成されています。各レッスンには動画が用意されています。動画では、全体的なコンセプトの個々の部分を扱います。各レッスンは、チュートリアル ワークフローの親ページ内の個別のページに保存されます。レッスンのページには、ユーザーがチュートリアルの前または次のレッスンに移動できるボタンがあります。非常に複雑なコンセプトには練習アクティビティが含まれることがあります。
動画と構造
動画では 1 つのコンセプトの概要を説明します。動画では、画面上でそのアクションを実行する際の指示が表示されます。サンプル動画は https://youtu.be/DkMP_VdGslU でご覧いただけます。この動画では、Setup Facility ウィザードの使い方を紹介しています。
この動画では、コールアウトとハイライト表示されたカーソルを使用して、この 1 つのコンセプトの手順をユーザーにわかりやすく説明しています。動画は YouTube でホストされます。YouTube でホストされている場合は、字幕が自動生成されます。その後、誤字脱字、文法、句読点について字幕を編集します。これらの字幕は、Amara などの翻訳ツールで翻訳するためにエクスポートできます。
動画には一貫したタイトル画面が表示されます。この点については、最初の数週間でメンターと話し合う予定です。また、一貫したコールアウト スタイル（矢印、カーソルによるハイライト表示、ボックス）を使用します。これは最初の数週間でメンターと一緒に決定します。
構造例
最もシンプルなワークフローである INSTALL-IMPORT は、チュートリアル全体です。このチュートリアルには、動画を含む 2 つのレッスンがあります。
- Kolibri 施設のダウンロード、インストール、設定
- Kolibri Studio でのコンテンツのインポート - この動画は他のワークフローから参照される可能性があります。
より高度なチュートリアルには、複数の動画を含む複数のサブレッスンが必要です。UPLOAD-EDIT-PUBLISH-UPDATE ワークフローは、次の構造に従います。
レッスン 1 - Kolibri Studio でのコンテンツのアップロードとチャンネルの作成
ユーザーの目標: このレッスンを修了すると、次のアクションを完了する方法を学びます。
- Kolibri で使用するチャンネルを Kolibri Studio で作成します。チャンネルのシークレット トークンを使用して、Kolibri にコンテンツ チャンネルをインポートする方法を学びます。
- Studio ライブラリ内の既存の公開チャンネルからコンテンツをインポートして、チャンネルを作成します。
- パソコンからコンテンツをアップロードしてチャンネルを作成する。
サブレッスン動画:
- サブレッスン 1 – Kolibri Studio で自分のチャンネルを作成し、既存の公開チャンネル（Khan Academy、PHET など）からコンテンツをインポートする: 動画 1 - 公開コンテンツ チャンネル（Kolibri Studio で公開チャンネルを表示） 動画 2 - チャンネルを作成する 動画 3 - 既存のチャンネルからコンテンツをインポートする 動画 4 - チャンネルを公開してシークレット トークンを取得する 動画 5 - シークレット トークンを使用してチャンネルを Kolibri にインポートする
- サブレッスン 2 - マイ ドキュメント コンテンツ チャンネルへのアップロード: 動画 1 - マイ ドキュメントからファイルをアップロードする 動画 2 - 独自の演習を作成する
レッスン 2 – Kolibri Studio でのチャンネルの高度な編集
ユーザーの目標: このレッスンの終わりまでに、次の操作を完了できるようになります。
- Kolibri Studio でコンテンツ チャンネルを編集する
- Kolibri Studio でコンテンツ チャンネルを管理する
サブレッスン動画:
- サブレッスン 1 - 演習の追加、フォルダ構造の整理、コラボレーション オプションによるコンテンツの編集（1 本の動画）
- サブレッスン 2 - コンテンツの削除や移動などのその他の機能の使用（1 本の動画）
レッスン 3 - Kolibri で使用するために Kolibri Studio チャンネルを公開する、チャンネルを更新する
ユーザーの目標: このレッスンの終わりまでに、次の操作を完了できるようになります。
- Kolibri Studio でチャンネルを公開し、新しいコンテンツを追加した後に再公開する
- チャンネルを更新する
- Kolibri にインポートするチャンネル トークンを取得する（この操作について説明しているレッスン 1 の前の動画へのリンクを参照）
サブレッスン動画:
サブレッスン 1 - チャンネルへの最新情報の公開
動画 1: チャンネルの再公開 動画 2: 追加コンテンツを追加した後、Kolibri でチャンネルを更新する