このページには、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. 現在のところ、PC ユーザー向けのドキュメントでは Sphinx Documentation Generator と「Google ドキュメントのテーマを読む」を使用しています。Android ポートで同じものを使用すれば、以下の点で便利です。 -> 両方のドキュメントを簡単に統合できる。 -> あらゆる画面サイズに最適化されています。-> デスクトップ ドキュメントから Android ユーザー ドキュメントに移動する際のシームレスなエクスペリエンス
- 応用上の相対的な位置に応じて、チャプター、セクション、サブセクションを分割する。たとえば、背景/PIP モードは [その他] -> [設定] -> [動画] にあるため、チャプターの構成は次のようになります。
- その他
- |__設定
- | |__メディア ライブラリ
- | |__動画 --> バックグラウンド/PIP モード
- : -> このアプローチでは、ユーザーは、アプリ内の相対的な場所と比較することで、サポートが必要な部分に簡単に移動できるため、アクセスしやすくなります。それぞれの特徴について、技術面と非技術面をさらに分けることができます。最初に技術的でないわかりやすい説明を記述してから、同じ機能の技術的な部分をそのすぐ下に強調したり、ラベルを付けたりします。繰り返し作業が必要になる場合もありますが、技術的な知識のない大部分の方もスムーズに対応できるようになります。これは、将来的に保守性が向上するためにも役立ちます。アプリが飽和状態になると、関連する UI はそれほど変化しない可能性が考えられます。そのため、今後新しい機能が追加または削除された場合は、そのセクションをリファクタリングするだけで済みます。UI 全体が変更された場合は、セクション/チャプターやドキュメント全体を再構築できます。どちらの場合も、現在の UI に合わせてスクリーンショットを置き換える必要があるため、ドキュメント全体を変更する必要があります。実際のデモは https://avinal.gitlab.io/vlc-android-docs/ でご覧いただけます。
ドキュメントの各セクションは、ラベル付きのスクリーンショット、機能の説明、技術的な部分（ある場合）、機能のヒントとコツで構成されます。
-> デスクトップからこのユーザー ドキュメントを独自に開発することで、現在のドキュメントに影響を与えたり、開発中に影響を受けることなく、わずか数ステップで両方のドキュメントをマージできます。作成したドキュメント全体をパソコン向けドキュメントの Android セクションに配置し、Android 向け VLC ドキュメントのパーマリンクを作成することをおすすめします。
-> さらなる改善として、パソコン ユーザー ドキュメントのスタートページを、ユーザーがお気に入りの OS を直接選択できるように再設計し、選択した OS のドキュメントにリダイレクトするなどの改善が行われる場合があります。Windows、MacOS、Linux の VLC ユーザー ドキュメントはすでに十分に設計、議論されているため、Windows/MacOS/Linux か、Android か iOS かの選択肢があるかもしれません。これにより、すべてのポートで 1 つのリンクを使用するだけで、適切に分離された統合ユーザー ドキュメントが作成されます。
提案されたユーザー ドキュメントの方が優れているのはなぜですか？ この提案されるユーザー ドキュメントは、エンドユーザーがサポートを求める一般的なパターンに基づいて構成されています。使いやすさ、明確さ、デザイン、技術的な知識など、使いやすさとエンドユーザー エクスペリエンスを最大限に高めるために必要な機能がすべて記載されています。また、ポートごとに個別のユーザー ドキュメントを維持する必要がなくなるため、メンテナンスも簡単です。
私がこのプロジェクトに適している理由 -> 私は 2 年以上もコードを記述してきましたが、特定のライブラリやソフトウェアの API ドキュメントを読むことや、独自のコードをドキュメント化しなければならないこともよくあります。そのため、人々がドキュメントに何を求めているか、どのような問題に直面しているか、どのようにサポートを求めるかが正確にわかります。同じ経験を応用して、一貫性があり、読みやすいドキュメントを作成できるようになると思います。
-> Quora や Stack Overflow など、さまざまなプラットフォームの技術記事を積極的に執筆しています。私は、物事をキャッチーにわかりやすく説明する方法を知っています。
-> Android 向け VLC はパワフルで有名なツールですが、その機能のほとんどは不明であるか、利用できるヘルプがありません。私はもう何年もの間、パソコン プラットフォームとモバイル プラットフォームの両方で VLC を使用しており、ユーザーが直面する可能性がある問題を知っています。自分の知識と経験を結集して、優れたドキュメントに仕上げることができました。