このページには、Google シーズンのドキュメントで受け入れられているテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- VLC
- テクニカル ライター:
- Abhishek Pratap Singh 氏
- プロジェクト名:
- VLC ユーザー ドキュメントのモダナイゼーションの続行
- プロジェクトの期間:
- 標準の期間（3 か月）
プロジェクトの説明
本ドキュメントの現状
VLC ユーザー ドキュメントは現在、モダナイズと更新が行われています。Wiki ベースの古いドキュメント [1] から、ReadTheDocs でホストされる Sphinx 構築の最新のユーザー ドキュメント [2] への移行が進行中です。
ターゲット オーディエンス
ターゲット ユーザーは、VLC メディア プレーヤーの機能を通常のメディア プレーヤーの枠を超えて探索したいと考えている好奇心旺盛なユーザーであると同時に、簡単なリファレンス ガイドとしてデベロッパーにも役立ちます。そこで、エンドユーザーが自由に選択できるように、GUI ベースの手順（関連する画像とともに）と CLI ベースの方法（コード スニペット）の両方を含める予定です。
ドキュメントの言語（特に GUI セクション）は、オペレーティング コンピュータの経験値が少ない人でも、ガイドを理解して実装できるような表現を薄くすべきだと考えています。その一方で、コーダーが興味を失うことが長すぎる、あるいは説明的になりすぎないようにする必要があります（特に CLI セクション）。
適切なバランスを取るには、ページの最初に前提条件に言及するか、熟練したユーザーがスキップできるようにオプションのセクションを残しておきます。
翻訳を構築する場合、英語と翻訳先の言語を十分に理解できる VLC のデベロッパー/ユーザーを対象とする。
ツール
新しいドキュメントの作成は Sphinx によって行われ、ReadTheDocs でホストされています。バージョン管理システムは GitLab に実装されています。私も Git と GitHub を使用した経験があり、GitLab のコツをつかむことができました。
Sphinx に関しては、他のオープンソース愛好家が、自分のドキュメントの作成に Sphinx を使用している組織が多いと気づいたときに読んでいました（ユーザー マニュアル [3] や API ドキュメント [4] の作成に Sphinx を使用している Blender の顕著な例です）。
バージョニングや技術ドキュメントのホスティングに適したツールである ReadTheDocs は、少し使い慣れていました。そのため、VLC のドキュメントをほとんど問題なく作成することができ、使用されている形式である再構造化テキストに慣れています。
翻訳に関しては、i18n と l10n を実装するために、Babel を使用して .po ファイルを生成します。現在は、Babel ワークフローと、Sphinx を使用して .mo ファイルを作成する方法についてよく理解しています。
ボンディング期間を利用して、前述のツールの複雑さについて理解を深めたいと思います。
成果物と週ごとのタイムライン
2019 年のプロジェクトの一環として、インストール、インターフェース、音声、動画、再生などの一部（基本機能のほとんど）はすでに対応済みです。そこで、2020 年のプロジェクトでは、ユーザー ドキュメントの高度な使用方法のセクションを更新し、作業を進めたいと思います。
成果物 1 [第 1 ～ 2 週]: #7[5] に記載されているとおり、コード変換ドキュメントを更新します。
- コード変換
- 複数の動画をコード変換する
- ロゴを追加
- 動画を結合する
- 音声を抽出してファイルから音声を抽出する
- DVD をリッピングする
成果物 2 [第 3 ～ 4 週]: Firefox 77、Chrome 83、Edge 83 でのテスト中に、VLC をウェブ プラグインとして使用して更新 [6]。
- 動画を使ったウェブページの作成
- 埋め込みタグ属性
- JavaScript API の説明
成果物 3 [第 5 週]: コマンドライン インターフェース [7] コマンドをテストし、それに応じて更新します。
- ストリーム
- モジュールの選択
- アイテム固有のオプション
- フィルタ
第 6 週: 上記 3 つの成果物のためのバッファ期間。
成果物 4 [7 ～ 8 週]: 翻訳の準備をする。 更新以外にも、他の言語への翻訳の準備をする予定。これは、翻訳後も英語の知識がないユーザーでもドキュメントを読むことができる（さらに VLC が世界支配への近道となる）ため、重要です [8]。
この提案の「ツール」の項で説明したように、現在 VLC では Babel を使用して翻訳用の .po ファイルを生成しています。ユーザー/ボランティアの以下のプロセスを文書化します。
- 基本ドキュメントをローカルでダウンロードしてビルドします。
- Babel を使用して必要なファイルを生成します。
- 文字列の「Translations」と入力します。
- Sphinx を使用して翻訳済みのドキュメントをビルドする。
- 変更を commit します。
成果物 5 [9 ～ 10 週]: モジュールのドキュメントを準備します。メンターと話し合ったとおり、2 つのパートに分けて、モジュールのドキュメントを準備する予定です。
パート - I: コードベースから有効なオプションを探し、対応する Wiki ページから 1 行の使用方法（およびデフォルト値）を抽出するスクリプトを使用して、モジュールの近くにファイルを作成します。これが基本的な下書きになります。
パート - II: 特定のプラットフォーム（Windows、時間が許せば Fedora も可能）のすべてのモジュール + プラグイン + オプションをリンクするプラットフォーム固有の構造を構築する
モジュールの近くにファイルを作成することで、ドキュメントとソースコードの近くを確保できます。ボトムトップ アプローチを使用して、パート I で作成したファイルを組み合わせ、パート II の構造を参照として使用して、メインのモジュール ドキュメントを作成します。
自動化によって作成されるファイルはレビューが必要ですが、最優先事項は機能的なフレームワークを作成することです。その準備が整い、時間の許す限り、ファイルを見直してオプションを検証いたします。このフレームワークは、利用可能になり次第、開発者と管理者がも関連するユースケースを追加することで貢献を開始できるようになるため、優先順位が付けられています。
ボーナス提供 [第 11 週]: 4.0 リリースの準備をする。 プロジェクトが予定どおりに進むよう、ボーナスの成果物を提案したいと思います。メンターたちにも説明したように、4.0 リリースに備えるには、バージョン 3.0 の安定したほぼ完全なドキュメントを用意する必要があります。
したがって、以下のセクションに記入済みのドキュメントに目を通し、上記の方法を確認、更新します。
- 基本的な使用方法: メディア、再生、音声、動画、字幕、ホットキー、録画、設定、ヒントとアドバイス。
- 高度な使用方法: プレーヤー、インターフェース、コード変換、ストリーミング、異常なケース
- アドオン: 拡張機能、スキン
12 週目: 上記 3 つの成果物と最終レポートのためのバッファ週。
私がこのプロジェクトに適している理由
テクノロジーに夢中なので、ソフトウェアを使用/テストした経験があります。また、ソフトウェアのコードベースから理解しようとすることもあります。実際、オープンソース組織のコードベースを理解しようとするときに、ドキュメントの重要性を実際に認識したのは初めてのことでした。さらに、私は音楽愛好家として、VLC を微調整した経験が数多くあります。
それとは別に、私は生涯にわたってリサーチャー兼ライターをしてきました。何かを書き留めなければまったく理解できません。その習慣のおかげで、効率的にメモを取り、記録することができるようになりました。
この 2 つの習慣が交わる点が、私が技術ドキュメントに適している理由です。技術的な側面をしっかりと理解するとともに、調査結果やプロセスをユーザーが理解できる形で文書化することができる。
リンク: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ Document[4] https://docs.blender.org/api/current/index.org[5]