このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- VLC
- テクニカル ライター:
- Abhishek Pratap Singh 氏
- プロジェクト名:
- VLC のモダナイゼーションに関するユーザー ドキュメントを続行する
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
ドキュメントの現在のステータス
VLC ユーザー ドキュメントは現在、モダナイゼーションと更新の過程にあります。ウィキベースの古いドキュメント [1] から、ReadTheDocs でホストされている Sphinx で構築された最新のユーザー ドキュメント [2] への移行が進行中です。
対象
対象読者は、一般的なメディア プレーヤーを超える VLC Media Player の機能を探求したい好奇心旺盛なユーザーと、簡単なリファレンス ガイドとしてデベロッパーにも役立つものです。そのため、エンドユーザーが自由に選択できるように、GUI ベースの手順（関連する場合は画像を含む）と CLI ベースの方法（コード スニペットを含む）の両方を記載する予定です。
ドキュメントの表現（特に GUI セクション）は、コンピュータの操作に慣れていないユーザーでもガイドを理解して実装できるように、十分に簡素化する必要があります。一方で、コード作成者の興味を失うほど長すぎたり、説明的すぎたり（特に CLI セクション）しないでください。
適切なバランスを実現するには、ページの冒頭に前提条件を記載するか、十分な知識をお持ちのユーザーがスキップできるオプションのセクションを用意します。
翻訳の作成対象は、英語と翻訳先の言語を十分に理解している VLC のデベロッパー/ユーザーです。
ツール
新しいドキュメントは Sphinx で作成され、ReadTheDocs でホストされています。バージョン管理システムは GitLab で実装されています。Git と GitHub の使用経験があったので、GitLab の使い方を習得できましたが、習得に時間のかかる機能もありました。
Sphinx については、他のオープンソース愛好家がドキュメントの作成にこのツールを使用していると述べた際に読んだことがあります（ユーザー マニュアル [3] と API ドキュメント [4]の構築に Sphinx を使用している Blender の顕著な例です）。
私は ReadTheDocs に少しだけ精通していました。これは、バージョニングと技術ドキュメントのホスティングに適したツールです。そのため、問題なく VLC のドキュメントを作成でき、使用されているフォーマットである reStructured Text にも精通しています。
翻訳については、VLC は Babel を使用して .po ファイルを生成し、i18n と l10n を実装しています。現在は、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 を使用して必要なファイルを生成します。
- 文字列の翻訳を入力します。
- Sphinx を使用して翻訳済みドキュメントを作成する。
- 変更を commit します。
成果物 5 [第 9 週～第 10 週]: モジュールのドキュメントを準備します。メンターと話し合ったとおり、私はモジュールに関するドキュメントを 2 部構成で準備する予定です。
パート I: コードベースから有効なオプションを検索し、対応するウィキページから 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/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35