このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- Wikimedia Foundation
- テクニカル ライター:
- Pavithra Eswaramoorthy 氏
- プロジェクト名:
- Wikimedia の技術ドキュメンタリーや動画撮影担当者向けのドキュメントを改善
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
1. 自己紹介
数か月前にオープンソース ソフトウェアに出会ったとき、すぐにその範囲が無限であることに圧倒されると感じました。膨大なプロジェクトを成功に導くために苦労する中で、Google Summer of Code and Outreachy のようなオープンソース イニシアチブについて学びました。Google ドキュメントのシーズンは面白そうで、Wikimedia Foundation のプロジェクトのアイデアが私の好奇心をそそり、さらに調査を始めました。
これまでのところ、わくわくするような刺激的で混乱するような体験もありました。「待って、何？」「ああ、わかった！」「これにコメントすべき？」といった具合です。Wikimedia のコミュニティはあらゆる段階でサポートしてくれました。ページの編集から拡張機能の作成まで、私は日々新しいことを学んでいます。
期待どおりのアプリケーション プロセスが、私のオープンソース コミュニティへの入り口のようなものでした。この提案は、私自身の初心者としての体験に触発されたものです。
2. プロジェクト
2.1. 枠線
このプロジェクトは、Wikimedia のテクニカル ライターと潜在的なビデオグラファー向けのドキュメントを改善することを目的としています。 成熟した一連の技術ドキュメント ガイドラインは、全体的なドキュメントの改善を促進し、スクリーンキャストを作成するための参照により、ソフトウェア機能を効果的にデモンストレーションできるようになります。これらの分野に関する既存のドキュメントは、新規参加者と経験豊富なコントリビューターの両方をより適切にサポートするために拡張できます。この便利なリソースからなるネットワークを、段階的に展開していきます。
2.2. 成果物
T197006 [https://phabricator.wikimedia.org/T197006] - ウィキメディアのドキュメンタリー作家向けのドキュメントを改善:
- ドキュメント/スタイルガイドにヒントと例を追加[https://www.mediawiki.org/wiki/Documentation/Style_guide]
- ユーザーガイド、ハウツー、クイックスタート ガイド、リリースノート、README など、技術ドキュメントのテンプレートや提案で、MediaWiki 固有の情報を特定のジャンルに追加します。[https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
- 技術ドキュメントの優先順位付けに関するガイドラインのテストと改善を行います。[https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
- さまざまなジャンルのドキュメントについてコンテンツ収集戦略を設計する。
- MediaWiki のドキュメントのコミュニケーションとコラボレーションの戦略を策定します。
- ライターが公開前にドキュメントを確認できるチェックリストを作成します。
- 新しいテクニカル ライターのドキュメント構造を拡張する。[https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
- ハッカソンに適した技術ドキュメント タスクのリストを作成する。[https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
- 便利なリソースを紹介したテクニカル ライターのハブを作成します。
MediaWiki のビデオグラファー向けのドキュメントを改善:
- 一般的なスクリーンキャストを作成するためのクイックユーザーガイドを作成する。
- チュートリアル用の MediaWiki 固有のスクリーンキャスト テンプレートを設計します。
T214522 [https://phabricator.wikimedia.org/T214522]- 「Introduction to Phabricator」スクリーンキャストを作成します。
2.3. ストレッチ目標
- 内容を再確認し、WikiProject スクリーンキャストのドキュメントを更新してください。(https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)
3. メンター
メンターとの主なコミュニケーション手段は Zulip です。コミュニティとのディスカッションには、Wikimedia の IRC チャンネルとメールを使用します。 特定のタスクに関するディスカッションは、Phabricator タスクのコメントセクションで行われます。
4. ディスカッション
このプロジェクトは、大きく 2 つのフェーズに分かれています。
(i) Wikimedia のテクニカル ライターの既存のリソースを改善する。
（ii）今後撮影する動画制作者に役立つテンプレートを作成する。
（i）Wikimedia のテクニカル ライターの既存のリソースを改善する。
過去には MediaWiki のドキュメントを改善する取り組みがいくつか行われており、成功の程度はさまざまです。たとえば
- https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
- https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
- https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
- https://www.mediawiki.org/wiki/User:Waldir/Docs
こうした取り組みから、テクニカル ライター向けのリソースを改善すれば、生成されるドキュメントに直接影響することがわかっています。
以下は、Outreachy 2018 のインターンである Anna e só 氏の隔週レポートの抜粋です（https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/）。
「MediaWiki のスタイルガイドは完璧とは言えません。特に外部からの参照に頼りすぎて、どのベスト プラクティスが最適かを強調していません。残念ながら、これは MediaWiki に限った問題ではありません。Translation のベスト プラクティスなど、他のドキュメントにも現れています。ライターが仕事をするのにふさわしい信頼できるリソースがないと、ターゲット ユーザーと適切な文章スタイルを確立することが難しくなります。また、ユーザー、特に新規ユーザーは、新しい概念やプロセスを理解する際に問題に直面する可能性があります。」
また、T197006 [https://phabricator.wikimedia.org/T197006] は、改善が必要な技術文書ドキュメントの特定の領域に光を当てています。明らかに、Documentation/Style_guide から始めるとよいでしょう。
優れたスタイルガイドが完成したら、次の一連のドキュメントでテクニカル ライティングのさまざまな段階をテクニカル ライターにガイドする予定です。ドキュメントは初心者に優しいものにすると同時に、ライターが後で参照する必要がある情報をすべて提供する必要があります。
準備の段階は、おそらく最も重要なことでしょう。ドキュメント作成の土台となるからです。この段階を通じてテクニカル ライターをサポートするために、関連情報を収集する効果的な方法と、テンプレートを使用してこの情報を構造化するためのヒントを説明するリファレンス ドキュメントが作成されます。
次は文章作成の段階です。ライターに、基準を自動的に高く設定するための良い例が提示される。さらに、すべてのドキュメントで従う必要のある一連の基本的な基準を使用してチェックリストが作成されます。これにより、ライターは公開前にドキュメントを確認しやすくなります。
これらのドキュメントがあっても、新しいテクニカル ライターには追加のサポートが必要であり、それを提供する必要があります。新人テクニカル ライター向けのガイドが改良され、ハッカソンに適したタスクのリストが難易度に応じて厳選されています。
最後に、ドキュメントの管理と保守のプロセスを理解するためのドキュメントである「技術ドキュメントの優先順位付け」をテストして改善します。
このフェーズを終えると、ドキュメント スタイル ガイドをサポートするテクニカル ライティング ガイド、リソース、例、提案、テンプレートが用意されます。
（ii）今後撮影する動画制作者に役立つテンプレートを作成する。
「グラフィックが関係する内容を学ぶうえで最も難しい方法の一つは、書式なしテキストを読むことです。また、マニュアルで誤ったバージョンのソフトウェアを参照していたとしたらどうなるでしょうか。テキストのみのマニュアルでは、通常使用する手がかりがすべて揃っていないため、アプリ内のメニューや言葉が変わると、一連のアクションを再現できないことが多くなります。
最良の方法は、隣に専門家がいるところで起きることでしょう。 スクリーンキャストは、静止画像と専門家が近くにあります。わかりやすいボイスで動く視覚的なデモが得られます。また、画面にテキスト アノテーションやアニメーションを表示することもできます。スクリーンキャストがエキスパートより優れている点は、毎日、毎時間自由に再生できることです。
また、スクリーンキャストに翻訳した字幕を追加して、母語の異なるユーザーも見られるようにしたり、音声トラックを別の言語に差し替えたりすることも可能です。」
上記の「The Screencasting Handbook」[https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] の抜粋で、Ian Ozsvald 氏はスクリーンキャストの意義について説明しています。このツールは、MediaWiki 開発環境のセットアップ、拡張機能の作成、Gerrit の使用などに関するチュートリアルで特に役立ちます。
ドキュメントのテンプレートと同様に、スクリーンキャストの標準テンプレートも使用すると統一性が高まり、閲覧者のエクスペリエンスが向上します。また、動画制作者にふさわしいものにするためのフレームワークも提供します。そこで、クイック ユーザーガイドと、紹介動画やチュートリアル動画を作成するためのテンプレートを用意しました。このドキュメントには、取り上げるコンセプトの詳細に関するポインタと、MediaWiki のスクリーンキャストのアイデアがいくつか含まれています。
上記のテンプレートをテストして、ストレッチ目標の準備をする最善の方法は、ツールとテンプレートを使用してスクリーンキャストを作成することです。そこで、「Pphabricator の概要」スクリーンキャストを作成し、Phabricator の基本的な使い方を説明しました。このプロセスで、議論の必要な分野も明らかになります。
最後に、Wikimedia の動画撮影者の中心的な参照ソースである WikiProject Screencast がレビューされ、更新されます。
5. 暫定的なタイムライン
コミュニティの絆を深める期間（8 月 1 日～ 9 月 1 日）
- メンターとともにプロジェクトを詳しく分析する。
次の点について話し合います。
- タスクを確認する頻度。
- スケジュールを共有し、週次または毎日のワークフローを決定する。
- 使用できるツールとリソース。
- 隔週および日次プロジェクト レポート。
Phabricator で必要なタスクとサブタスクを作成します。
ドキュメントの作成段階での個人的な任務を補うために、下書きを作成します。
第 1 週（9 月 2 日～ 8 日）
Documentation/Style_guide を改善:
- MediaWiki のベスト プラクティスと標準を説明することに主眼を移します。
- 良い例を取り入れて、関連ページの視認性を高める。
新規テクニカル ライター向けガイドの改善:
- ドキュメント構造を開きます。
第 2 週（9 月 9 日～ 15 日）
技術ドキュメントの優先順位付けに取り組む:
- ドキュメント ワークボードを評価し、適切なタスクの説明と優先順位付けの例を見つけます。
- トレンドを調べて、よくある問題を書き留めます。
- 情報と例を使用して、優先度の基準を文書化します。
第 3 週（9 月 16 日～ 22 日）
テクニカル ライター向けに次の追加ドキュメントを作成します。
- 技術ドキュメントを公開前に確認する際に役立つチェックリストです。
- さまざまなドキュメント ジャンルのコンテンツを効果的に収集する方法。
第 4 週（9 月 23 日～ 29 日）
最も一般的な MediaWiki ジャンルの記述に関する情報を、技術ドキュメントのテンプレートと提案に追加します。
- ユーザーガイド、クイック スタートガイド、README、リリースノート、ハウツーなどの作成に関する MediaWiki のベストプラクティスを文書化します。
テクニカル コミュニケーションの成熟度を高めるための指示を追加します。[https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]
第 5 週（9 月 30 日～ 10 月 6 日）
新しい共同編集者のオンボーディングに関するドキュメントの改善:
- ページを更新: ハッカソンの技術ドキュメントのタスク（タスク: プロジェクト期間中、適切なタスクをこのページに追加）
テクニカル ライターのハブを構築する
- 有益なページやリソースへのリンクを含むランディング ページを作成します。
- 新しいページと既存のページに必要なリンクを追加して、ページ間を簡単に移動できるようにします。
第 6 週（10 月 7 日～ 13 日）
MediaWiki の動画作成に関する次のドキュメントを作成します。
- スクリーンキャスト プロジェクトについて説明した「一般的なスクリーンキャストの作成」に関するクイックユーザーガイド。
- テンプレート: ソフトウェアやツールの使用方法のチュートリアル、新しいツールの開発に関するチュートリアル。
MediaWiki のスクリーンキャストのアイデアのリストを作成します。
第 7 週（10 月 14 日～ 20 日）
「Introduction to Phabricator」動画の作成:
- 前週に作成したテンプレートを使用してスクリプトの下書きを作成します。
- テンプレートの効率を見積もり、必要に応じて改善します。
- フィードバックを得て下書きを確定する。
第 8 週（10 月 21 日～ 27 日）
「Introduction to Phabricator」動画を公開:
- ソフトウェアを選択してインストールします。
- 環境を設定して、スクリーンキャストを作成します。
- 発生した問題と解決策をメモします。
第 9 週（10 月 28 日～ 11 月 3 日）
スクリーンキャスト プロジェクトのドキュメントの改善に取り組む:
- 構成を確認し、変更の必要性について話し合います。
- 対象のソフトウェアを確認します。
- ソフトウェアのリストを調査し、更新する。
第 10 週（11 月 4 日～ 10 日）
スクリーンキャスト プロジェクトのドキュメントを継続的に改善します。
- チュートリアルとスクリプトを評価して改善します。
- スクリーンキャスト ギャラリーを確認します。
第 11 週（11 月 11 日～ 17 日）
スクリーンキャスト プロジェクトのドキュメントに関する作業を完了します。
- 新しい動画を見つけてギャラリーに追加します。
- 必要な構造を変更します。
第 12 週（11 月 18 日～ 24 日）
保留中のタスクに対処します。
最終レポートを作成する:
- 隔週または日次レポートを参照して、必要な情報を収集します。
- レポートの構成を計画し、下書きを作成します。
- メンターのフィードバックに基づいて下書きを改善し、完成させる。
第 13 週（11 月 25 日～ 29 日）
- 最終報告とメンターによる評価を送信します。
6. 進捗状況の記録
毎日、達成状況が Zulip を通じて私のメンターに伝えられます。Wikimedia コミュニティは、Phabricator や隔週のプロジェクト レポートで進捗状況を追跡することができます。
7. その他のコミットメント
私は全日制の大学生で、秋学期が「ドキュメント シーズン」のタイムラインと重なっています。ですから、私は大学の試験も勉強しています。
1 回目の社内試験: 8 月 18 日～ 24 日
2 回目の社内試験: 9 月 29 日～ 10 月 6 日
学期末試験: 11 月 11 日～ 30 日
また、今年は好開催地となったため、10 月 12 日から 15 日まで開催される初の公開カンファレンスである PyCon India にも 10 月 12 日から 15 日まで参加する予定です。新しい人と出会い、洞察に満ちた会話をする絶好の機会になると思います。
これらのコミットメントを管理するために、暫定的なタイムラインには、対応する週のタスクの重要度が下がっています。ドキュメントの作成に十分な時間を確保するために、秋学期に修了する主要クレジットを 20 クレジット以下にする。（通常の学生は 1 学期あたり平均 25 クレジットを修了します）