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

Wikimedia Foundation プロジェクト

このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。

プロジェクトの概要

オープンソース組織:: The Wikimedia Foundation
テクニカルライター:: Pavithra Eswaramoorthy
プロジェクト名:: ウィキメディアの技術ドキュメンタリー制作者とビデオ制作者向けのドキュメントを改善
プロジェクトの長さ:: 標準期間（3 か月）

プロジェクトの説明

1. 自己紹介

数か月前にオープンソースソフトウェアを初めて知ったとき、その無限の可能性に圧倒されました。膨大なプロジェクトを進めていくうちに、Google Summer of Code や Outreachy などのオープンソースイニシアチブについて知りました。Google Season of Docs は興味深く、ウィキメディア財団のプロジェクトアイデアにも興味をそそられたので、さらに詳しく調べ始めました。

これまでの道のりは、ワクワクと混乱が半々で、「えっ、どういうこと？」「あ、わかった！」「これについてコメントすべき？」など、さまざまな思いが交錯しました。Wikimedia コミュニティは、あらゆる段階でサポートしてくれました。ページの編集から拡張機能の作成まで、毎日新しいことを学んでいます。

予想どおり、申請プロセスはオープンソースコミュニティへのゲートウェイとなりました。この提案は、初心者としての私自身の経験に基づいています。

2. プロジェクト

2.1. アウトライン

このプロジェクトは、ウィキメディア全体の技術ライターと潜在的なビデオグラファー向けのドキュメントを改善することを目的としています。技術ドキュメントのガイドラインが確立されていれば、全体的なドキュメントの質を高めることができます。また、スクリーンキャストの作成に関するリファレンスがあれば、ソフトウェアの機能を効果的にデモできます。これらの分野の既存のドキュメントを拡張することで、初心者と経験豊富なコントリビューターの両方をより適切にサポートできます。この便利なリソースのネットワークを開発するには、段階的なアプローチが採用されます。

2.2. 成果物

T197006 [https://phabricator.wikimedia.org/T197006] - Wikimedia の文書作成者向けの文書を改善:
- ドキュメント/スタイルガイドにヒントと例を追加します。[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]- 「Phabricator の概要」スクリーンキャストを作成。

2.3. ストレッチゴール

コンテンツを再確認し、WikiProject Screencast のドキュメントを更新します。(https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. メンター

メンターとの主なコミュニケーション手段は Zulip です。コミュニティとのディスカッションには、Wikimedia の IRC チャネルとメールを使用します。特定のタスクに関するディスカッションについては、Phabricator タスクのコメント欄で行います。

4. ディスカッション

このプロジェクトは大きく次の 2 つのフェーズに分かれています。

（i）ウィキメディアの技術ライター向けの既存のリソースを改善する。

（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ó の 2 週間ごとのレポートの抜粋です（https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/）。

「MediaWiki のスタイルガイドは完璧とは言えません。特に、どの手法が最良と考えられているかが明らかにされず、外部参照に過度に依存しているために特にそうです。残念ながら、これは MediaWiki だけに限った問題ではなく、Translation のベストプラクティスなどの他のドキュメントにも記載されています。ライターは、信頼できる優れたリソースがないため、対象読者と適切な文章スタイルを確立できず、ユーザー（特に新規ユーザー）は、新しいコンセプトとプロセスを理解するのに苦労する可能性があります。」

T197006 [https://phabricator.wikimedia.org/T197006] では、技術的な記述のドキュメントの改善が必要な特定の領域についても説明しています。Documentation/Style_guide が出発点であることは明らかです。

より優れたスタイルガイドが完成したら、次は技術文書作成のさまざまな段階を技術ライターに案内するドキュメントを作成していく予定です。ドキュメントは初心者向けであるとともに、ライターが参照できる必要な情報をすべて提供する必要があります。

準備段階は、ドキュメントの基盤を築くため、最も重要な段階です。この段階で技術ライターをサポートするために、関連情報を効果的に収集する方法と、テンプレートを使用して情報を整理する方法に関するヒントが記載されたリファレンスドキュメントが作成されています。

次に、記述段階です。ライターには優れた作品の例が提供され、自動的に高い基準が設定されます。さらに、すべてのドキュメントが遵守する必要がある一連の基本的な基準を含むチェックリストが作成されます。これにより、作成者は公開前にドキュメントを確認できます。

これらのドキュメントがあっても、新しい技術ライターは追加のサポートを必要とします。そのサポートを提供する必要があります。新しい技術ライター向けのガイドが改良され、ハッカソンに適したタスクのリストが難易度に基づいてキュレートされました。

最後に、ドキュメントの管理とメンテナンスのプロセスを理解するためのドキュメント「技術ドキュメントの優先順位付け」がテストされ、改善されました。

このフェーズが終了すると、ドキュメントスタイルガイドをサポートする技術的なライティングガイド、リソース、例、提案、テンプレートのハブが確立されます。

（ii）潜在的な動画制作者向けの便利なテンプレートを作成する。

「グラフィックに関わるものを学ぶ最も難しい方法の一つは、書式なしテキストを読むことです。また、マニュアルに記載されているソフトウェアのバージョンが間違っていた場合も、通常使用する手がかりがないため、アプリケーションのメニューや文言が変更されると、一連の操作を再現できなくなることがよくあります。

最善の方法は、専門家が隣に座って指導してくれることです。スクリーンキャストとは、静的なグラフィックと専門家によるサポートの中間に位置するものです。視覚的な動的なデモと親しみやすい音声が提供され、画面にテキストアノテーションやアニメーションを表示することもできます。エキスパートに比べてスクリーンキャストの利点は、毎日 1 時間ごとに自由に再生できることです。

翻訳された字幕をスクリーンキャストに加えて、母国語以外のユーザーが視聴できるようにしたり、音声トラックを別の言語に置き換えたりすることもできます。」

「The Screencasting Handbook」[https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] からの上記のスニペットでは、Ian Ozsvald がスクリーンキャストの重要性について説明しています。MediaWiki 開発環境の設定、拡張機能の作成、Gerrit の使用などのチュートリアルに特に役立ちます。

ドキュメントのテンプレートと同様に、スクリーンキャストの標準テンプレートを使用すると、統一性が促進され、視聴者のエクスペリエンスが向上します。また、映像制作を検討している方には、始めるためのフレームワークを提供します。そのため、クイックユーザーガイドと、紹介動画とチュートリアル動画を作成するテンプレートが作成されています。このドキュメントには、説明するコンセプトの深度に関するヒントと、MediaWiki のスクリーンキャストのアイデアがいくつか記載されています。

上記のテンプレートをテストし、ストレッチ目標に備える最善の方法は、ツールとテンプレートを使用してスクリーンキャストを作成することです。そこで、Phabricator の基本的な使い方を説明する「Introduction to Phabricator」スクリーンキャストを用意しました。このプロセスでは、議論が必要な領域も明確になります。

最後に、ウィキメディアのビデオグラファー向けの主要な参照資料である WikiProject Screencast が確認され、更新されました。

5. 暫定的なタイムライン

コミュニティボンディング期間（8 月 1 日～ 9 月 1 日）

メンターとプロジェクトを詳細に分析する。
以下について話し合います。
- タスクの確認頻度。
- スケジュールを共有し、週単位または日単位のワークフローを決定します。
- 使用できるツールとリソース。
- 隔週および毎日のプロジェクトレポート。
Phabricator で必要なタスクとサブタスクを作成します。
下書きを作成して、ドキュメント作成の段階での個人的な約束の代わりとして利用します。

第 1 週（9 月 2 日～ 9 月 8 日）

Documentation/Style_guide を改善しました。
- 主な焦点を MediaWiki のベストプラクティスと標準に移行します。
- 優れた作品の例を掲載し、関連するページの視認性を高めます。
新しいテクニカルライター向けのガイドを改善しました。
- ドキュメント構造を拡張します。

第 2 週（9 月 9 日～ 9 月 15 日）

技術ドキュメントの優先順位付けの作業:
- ドキュメントワークボードを評価し、優れたタスクの説明と優先順位付けの例を見つけます。
- 傾向を調べ、一般的な問題をメモします。
- 情報と例を使用して、優先順位付け基準を文書化します。

第 3 週（9 月 16 ～ 22 日）

テクニカルライター向けに次の追加ドキュメントを作成します。
- 公開前に技術ドキュメントを確認するのに役立つチェックリスト。
- さまざまなドキュメントジャンルのコンテンツを効果的に収集する方法。

第 4 週（9 月 23 日～ 9 月 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 日～ 10 月 13 日）

MediaWiki の動画制作に関する次のドキュメントを作成します。
- スクリーンキャストプロジェクトを指す「一般的なスクリーンキャストの作成」に関するクイックユーザーガイド。
- テンプレート: ソフトウェア/ツールの使用方法のチュートリアル、新しいツールの開発に関するチュートリアル。
MediaWiki のスクリーンキャストのアイデアのリストを作成する。

第 7 週（10 月 14 日～ 20 日）

「Phabricator の概要」動画の作成:
- （前の週に作成した）テンプレートを使用してスクリプトの下書きを作成します。
- テンプレートの効率を推定し、必要に応じて改善します。
- フィードバックを得て、ドラフトを完成させる。

第 8 週（10 月 21 日～ 10 月 27 日）

「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. その他のコミットメント

私はフルタイムで大学に通っており、秋学期はドキュメンタリーシーズンの期間と重なります。そのため、大学の試験など、さまざまな約束があります。

最初の内部試験: 8 月 18 日～ 24 日

第 2 回内部試験: 9 月 29 日～ 10 月 6 日

学期末試験: 11 月 11 日～ 30 日

また、今年は場所が好調だったので、10 月 12 日から 15 日まで開催される初めての公開カンファレンスである PyCon India に出席するつもりです。新しい人と出会い、有意義な会話を交わす絶好の機会になると思います。

これらのコミットメントを管理するため、暫定的なタイムラインには、対応する週に重要度の低いタスクが含まれています。ドキュメントの作成に十分な時間を確保するため、秋学期に修得するコア単位は 20 単位以内にします。（通常の学生は 1 学期に平均 25 単位を修了します）