このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソースの組織:
- VLC
- テクニカル ライター:
- Avii
- プロジェクト名:
- 1 つのモバイル ポート（Android）の VLC ユーザー ドキュメントを作成する
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
ABSTRACT
ユーザー ドキュメントは、エンドユーザーを支援するための静的なサポート システムとして使用されます。商品やサービスに関する技術的な情報と非技術的な情報の両方を提供するものです。ソフトウェアやサービスの使い方をユーザーに説明するのに役立ちます。ちょっとした指示、ヒント、コツが必要なだけなのに、サポートに連絡したり、メールの返信を待ったりしたくないというユーザーもいます。ユーザー ドキュメントはまさにその役割を果たします。また、サポート費用の削減にもつながり、プロダクトの健全性とデベロッパー チームのアイデンティティを示すものとなります。
VLC for Android は、Google Play ストアだけで 1 億回以上ダウンロードされています。VLC には、音声と動画の再生からネットワーク ストリームまで、モバイル ポート向けの多くの機能が用意されています。このような素晴らしい機能を使用したいと望んでも、それができないことが多いのです。そのためにブログやランダムな動画を探すには多くの時間と忍耐が求められ、それでも取得される情報の信頼性はありません。現在、VLC は Wiki ページで Android 向け VLC ユーザー ドキュメントをホストしており、これらの機能に関する説明は少なく、またはまったくありません。また、ウィキページの最終更新日は 2019 年 3 月です。現在のプロジェクトでは、Android ポート向けに、モダンなデザインで使いやすくした新しいユーザー ドキュメントを提供します。
現在の状況
Wiki ページは完全に古く、最新バージョンの VLC に関する情報はごくわずかです。また、操作も簡単ではありません。英語以外の言語でドキュメントを読むオプションは表示されません。機能の説明は一切含まれていません。
分析
-> 現在、現在のドキュメントは古くなっていて、別のプラットフォームとツールを使用して新しい方法で作成する必要があります。
-> ほとんどの Android ユーザーは技術的な知識がほとんどないか、まったくありません。ただし、機能についてより技術的な情報を必要とするユーザーもいます。上記の目的ごとに 2 つのドキュメントを作成して維持することはおすすめしません。同じドキュメント内で、技術的な機能と技術的でない機能に分割すると、さらに混乱が生じます。ほとんどのユーザーは表示される UI や使用する機能に慣れているため、技術的な問題かどうかを判断するのは簡単ではありません。そのため、このプロセスを簡素化したいと考えています。
-> ほとんどのユーザーは、スマートフォン自体で情報を入手しようとし、残りはデスクトップや他のデバイスで入手しようとします。そのため、ドキュメントはあらゆる画面サイズに簡単に適応できる必要があります。ナビゲーションについて混乱を招くものであってはなりません。
-> パソコン版のすべての機能が Android 版で利用できるわけではありません。また、利用可能な機能でも、両方のポートで同じように動作するとは限りません。これは、パソコン向けアプリケーションは長い間開発されてきたため、ある種の飽和状態に達しているのに対し、モバイル ポートは比較的新しく、まだ開発中であるためです。それ以外にも、最近のモバイル デバイスは非常に高性能になっていますが、エンドユーザーの需要が主な理由で、組み込むことができる機能の種類には明らかな制限があります。誰も使用しない機能は、開発リソースの浪費です。そのため、機能に基づいて両方のドキュメントを参照することはおすすめしません。
上記の分析結果に基づき、以下を提案いたします。 1. 現在、パソコンのユーザー向けドキュメントでは、Sphinx ドキュメント ジェネレータと Read the Docs テーマを使用しています。Android ポートでも同じ名前を使用すると、次のメリットがあります。 -> 両方のドキュメントを簡単に統合できます。-> すべての画面サイズに最適化されています。-> パソコン向けドキュメントから Android ユーザー向けドキュメントに移動する際のシームレスなエクスペリエンス
- アプリケーション内の相対的な位置に応じて、章、セクション、サブセクションを分離します。たとえば、バックグラウンド モード/PiP モードは [その他] -> [設定] -> [動画] 内にあるため、チャプターの構造は次のようになります。
- もっと見る
- |__設定
- | |__メディア ライブラリ
- | |__動画 --> バックグラウンド/PiP モード
- : -> このアプローチでは、ユーザーがアプリ内の相対的な位置と比較して、サポートが必要な部分に簡単に移動できるため、アクセスしやすくなります。各機能は、技術的な部分と技術的でない部分にさらに分割できます。まず、技術的な専門用語を使わない簡単な説明を記述し、同じ機能の技術的な部分（ある場合）をそのすぐ下にハイライト表示またはラベル付けします。繰り返しが発生する可能性がありますが、技術者以外の大多数のユーザーがスムーズに操作できるようにします。これは、将来的な保守性の向上にもつながります。アプリが飽和状態に達すると、相対的な UI はほとんど変更されないため、将来、新しい機能を追加または削除する場合は、そのセクションをリファクタリングするだけで済みます。UI 全体が変更された場合は、セクション/章の並べ替えやドキュメント全体の再構成を行います。いずれの場合も、現在の UI に合わせてスクリーンショットを置き換える必要があるため、ドキュメント全体に変更を加える必要があります。動作デモは、https://avinal.gitlab.io/vlc-android-docs/ でホストされています。
ドキュメントの各セクションには、ラベル付きのスクリーンショット、機能の説明、技術的な部分（該当する場合）、機能に関するヒントとコツが含まれます。
-> このユーザー ドキュメントをデスクトップで個別に開発することで、現在のドキュメントに影響を与えることなく、または開発中に影響を受けることなく、両方のドキュメントを数ステップで統合できます。このドキュメントが完成したら、デスクトップ向けドキュメントの Android セクションに配置し、VLC for Android ドキュメントのパーマリンクを作成することをおすすめします。
-> パソコン向けユーザー ドキュメントの開始ページを再設計し、ユーザーが希望する OS を直接選択して、選択した OS のドキュメントにリダイレクトできるようにするなど、さらに改善を進めていく予定です。Windows、macOS、Linux の VLC ユーザー ドキュメントはすでに適切に設計され、説明されているため、Windows / macOS / Linux または Android / iOS から選択できるオプションを追加する場合があります。これにより、すべてのポートで使用できる 1 つのリンクで、ユーザー ドキュメントが適切に分離され、統合されます。
提案したユーザー向けドキュメントが優れている理由この提案されたユーザー ドキュメントは、エンドユーザーがサポートを受ける一般的なパターンに基づいて構成されています。ドキュメントには、使いやすさとエンドユーザー エクスペリエンスを最大化するために必要なすべての機能（シンプルさ、明確さ、ルック＆フィール、技術的な知識など）が組み込まれています。また、ポートごとに個別のユーザー ドキュメントを維持する必要がなくなるため、メンテナンスが容易になります。
なぜこのプロジェクトに適任なのか？ -> 2 年間コードを記述していますが、特定のライブラリやソフトウェアの API ドキュメントを確認したり、独自のコードを記述したりすることがよくあります。そのため、ユーザーがドキュメントに求めるもの、直面している問題、サポートを求める方法を正確に把握しています。同じ経験を活かして、一貫性があり読みやすいドキュメントを作成できるようになります。
-> Quora、Stack Overflow、その他のさまざまなプラットフォームで技術的な記事を積極的に執筆しています。物事をキャッチーで理解しやすい方法で説明する方法を知っています。
-> Android 版 VLC は強力で非常に有名なツールですが、その機能のほとんどは知られていないか、ヘルプが提供されていません。私は長年、パソコンとモバイルの両方のプラットフォームで VLC を使用してきました。ユーザーが直面する可能性のある問題を把握しています。これまでの知識と経験を活かして、優れたドキュメントを作成いたします。