このページには、Google シーズンの Google ドキュメントで承認されたテクニカル ライティング プロジェクトの詳細が記載されています。
プロジェクトの概要
- オープンソースの組織:
- VLC
- テクニカル ライター:
- Avii
- プロジェクト名:
- 1 つのモバイルポート用の VLC ユーザー ドキュメントを作成する（Android）
- プロジェクトの期間:
- 標準の長さ（3 か月）
プロジェクトの説明
概要
ユーザー ドキュメントは、エンドユーザーを支援するための静的なサポート システムとして使用されます。製品やサービスに関する技術情報と非技術情報の両方を提供します。ソフトウェアやサービスの使い方を学ぶために役立つ。ちょっとした指示やヒント、コツさえあれば、サポートへの問い合わせやメールの返信を待っている人はいないでしょう。ユーザードキュメントはそれを行います。また、サポート費用を削減できるほか、プロダクトの健全性とデベロッパー チームの ID になります。
Android 向け VLC は、Google Play ストアだけで 1 億回以上ダウンロードされています。VLC は、音声とビデオの再生からネットワーク ストリームに至るまで、モバイルポート向けに多くの機能を備えています。こうした優れた機能を使用したいと望むユーザーは多いのですが、それは実現できません。ブログやランダムな動画を探すには多くの時間と忍耐が必要ですが、それでも、入手した情報の真正性は得られません。現在、VLC は Wiki ページ上に Android 向け VLC のユーザー ドキュメントをホストしていますが、これらの機能については説明がほとんどまたはまったく記載されていません。さらに、Wiki ページの最終更新日は 2019 年 3 月です。現在のプロジェクトでは、最新のデザインと Android ポートの使いやすさが向上した新しいユーザー ドキュメントが提供されます。
現在の状況
Wiki ページは完全に古く、VLC の最新バージョンに関する情報はほとんど含まれていません。また、操作も容易ではありません。英語以外の言語でドキュメントを読むオプションは表示されません。機能の説明がまったく含まれていません。
分析
-> 現時点では、現在のドキュメントは古くなっているため、新しい方法で別のプラットフォームとツールを使用して作成する必要があります。
-> ほとんどの Android ユーザーは技術的な知識がほとんどないかまったくありません。しかし、機能に関する技術的な情報を必要とするユーザーもいます。上記の目的ごとに 2 つのドキュメントを別々に作成、管理することはおすすめしません。あるいは、同じドキュメントでも、機能を技術面と技術面以外で区別すると、混乱が生じます。繰り返しになりますが、ほとんどのユーザーは表示される UI や使用する機能に慣れているため、誰もが技術的なものか非技術的なものかを判断するのは簡単ではありません。そのため、この点をわかりやすくする必要があります。
-> ほとんどのユーザーはスマートフォン自体で情報を入手しようとし、パソコンやその他のデバイスを使用します。そのため、ドキュメントはあらゆる画面サイズに簡単に適応できる必要があります。ナビゲーションに関して混乱が生じない。
-> PC 版のすべての機能が Android ポートで使用できるわけではなく、利用できる場合でも、両方のポートで同じように動作しない。これは、デスクトップ アプリケーションが長期間にわたって開発され、ある種の飽和状態に達しているためです。一方、モバイルポートは比較的新しく、まだ開発中です。それ以外は、昨今のモバイル・デバイスがますますパワフルになりつつありますが、主にエンドユーザーの需要により、組み込める機能のタイプには明らかな制限があります。誰も使用していない機能があると、開発リソースの無駄になります。そのため、機能に基づいて両方のドキュメントをやり取りすることはおすすめしません。
上記の分析に基づき、以下を提案します。 1. 現在のところ、デスクトップ ユーザー向けドキュメントでは Sphinx Documentation Generator と 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 を使用してきましたが、ユーザーが直面する可能性のある問題はわかっています。すべての知識と経験を総合して、優れたドキュメントが保証される。