このページでは、Google Season of Docs に承認された技術文書作成プロジェクトの詳細について説明します。
プロジェクトの概要
- オープンソース組織:
- VideoLAN
- テクニカル ライター:
- Edidiong Anny Asikpo
- プロジェクト名:
- VLC ユーザー ドキュメントをモダナイズ（書き換え）する
- プロジェクトの長さ:
- 標準期間（3 か月）
プロジェクトの説明
ABSTRACT
ユーザー向けドキュメントは、エンドユーザーがプロダクトやサービスを使用できるように設計されています。優れたユーザー ドキュメントは、ユーザーがソフトウェアの使用方法、機能、ヒント、コツを習得し、ソフトウェアの使用時に遭遇する一般的な問題を解決する方法を提供するため、非常に重要です。また、サポート費用を削減し、プロダクトの企業アイデンティティの一部となります。優れたユーザー ドキュメントは、プロダクトとデベロッパー チームの健全性の証です。
適切なユーザー ドキュメントがなければ、ユーザーは上記の作業を効果的かつ効率的に行う方法を理解できません。ユーザー ドキュメントは、プロダクトの成功を左右する重要な役割を果たします。優れたコミュニケーションは、ビジネスやプロダクトの中心であり、今後もそうであり続けるからです。優れたドキュメントは、そのコミュニケーションを、誰もがアクセスして成功を収めることができる管理可能なフレームワークにまとめます。
本稿執筆時点で、VLC のユーザー ドキュメントへのアクセス回数は 4,634,065 回、VLC Media Player のメインウェブサイトからのダウンロード数は毎月約 2,300 万回に上っています。これは、世界中の多くのユーザーが VLC Media Player を使用していることを示しています。メディア プレーヤーの使用方法については、ユーザー ドキュメントをご覧ください。ただし、VLC Media Player のユーザー ドキュメントは現在古く、不完全です（最終更新日: 2015 年 10 月 28 日）。VideoLAN コミュニティは、このプロジェクトを利用してユーザー ドキュメントを改善し、エンドユーザーが VLC Media Player をシームレスに使用できるようにしたいと考えています。
現在の状態
現在、ユーザー向けのドキュメントはウィキページで公開されています。古く、不完全で、ナビゲーションや情報の検索が難しく、メディア プレーヤーの最新バージョンに関する情報は掲載されていません。また、ドイツ語にしか翻訳されていないため、英語を読めない人には大きな障害となっています。
提案したユーザー向けドキュメントが現在のドキュメントよりも優れているのはなぜですか？
提案するユーザー ドキュメントは、エンドユーザーの効率、一貫性、安心感を改善し、確保できるように構成されます。書面によるガイドと関連する画像が含まれ、VLC メディア プレーヤーの各機能の使用方法に関する手順と説明が記載されています。最新の状態であり、簡単に操作でき、わかりやすく、少なくとも 5 つの主要言語に翻訳可能です。
メンター: ジャンバティスト、アレックス、サイモン
分析
Jean-Baptiste と私は、改善のために現在のユーザー ドキュメントを移行する新しい環境について話し合いました。Sphinx で記述されたソースファイルの Gitlab リポジトリと、Read the Docs でホストされているメイン ドキュメントの 2 つのリンクを共有したところ、新しいドキュメントもこれに似たものになるだろうとのことです。これらのツールの仕組みを理解するために、私は多くの調査を行いました。
スフィンクス
Sphinx は、ソフトウェアのドキュメント化に適した堅牢で成熟したソリューションです。シングルソース パブリッシング、インクルードによるコンテンツの再利用、コンテンツ タイプとタグに基づく条件付きインクルード、モバイルとデスクトップで優れたユーザー エクスペリエンスを提供する複数の成熟した HTML テーマ、ページ、ドキュメント、プロジェクト間の参照、インデックスと用語集のサポート、国際化のサポートなど、ライターが期待する多くの機能が含まれています。また、マークアップ言語として reStructuredText を使用しています。その強みの多くは、reStructuredText の強力さとわかりやすさ、ドキュメントを翻訳する機能にあります。
ドキュメントを読む
ドキュメントの作成、バージョニング、ホスティングを自動化することで、ソフトウェアのドキュメントを簡素化できます。同期が解除されることはありません。つまり、Git、Mercurial、Bazaar、Subversion など、お気に入りのバージョン管理システムにコードを push するたびに、Read the Docs がドキュメントを自動的にビルドするため、コードとドキュメントは常に最新の状態になります。複数のバージョンがあります。Read the Docs では複数のバージョンのドキュメントをホストしてビルドできるため、バージョン コントロール システムに別々のブランチまたはタグを作成するのと同じくらい簡単に、ドキュメントのバージョン 1.0 とバージョン 2.0 を用意できます。Read the Docs は無料のオープンソースで、ほぼすべての人間の言語とコンピュータ言語で、大規模および小規模のオープンソース プロジェクトの約 100,000 件のドキュメントがホストされています。
判定
Sphinx は非常に強力なツールであり、Read the Docs は Sphinx をベースに構築されており、Sphinx ドキュメントのホスティングを提供して、バージョン間でドキュメントを最新の状態に保ちます。これらは、デベロッパーと技術ライターがエンドユーザーに最適なユーザー ドキュメントを作成するために使用できる優れたツールセットです。
Sphinx には、ドキュメントを複数の言語に翻訳する機能が含まれています。ドキュメントの管理に使用するバージョン管理をサポートしています。誰でも編集でき、正しい情報が追加されない現在のウィキとは異なり、このバージョン管理システムでは、メイン リポジトリにマージされる前に、すべての変更が審査されます。バージョン管理により、ユーザーが問題を作成したり、プル リクエストを送信したりできるため、ドキュメントへのオープンソースの貢献も増えます。Sphinx と Read the Docs は、ASP.NET、Kernel、Julia、Jupyter、PHPMyAdmin、Write the Docs などの優れたコミュニティで使用されており、新しい VLC ユーザー ドキュメントに使用するのに適したツールです。
これらのツールについて読んだだけでなく、基本的なサンプルも作成しました。こちらのリンクは https://gitlab.com/Didicodes/demo-vlc-user-documentation で、私の GitLab リポジトリへのリンクです。また、readthedocs でホストされているバージョンは [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/) で確認できます。
提案されているドキュメントの構造
VLC ユーザー ドキュメントの構造を作成しました。こちら（https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing）をご覧ください。この新しい構造の導入を開始する前に、メンターから承認を得る必要があります。つまり、メンターによる確認後に構造が変更される可能性があります。
プロジェクトの目標
- ドキュメントを再編成します。
- 最新バージョンの VLC に合わせてドキュメントを更新しました。
- Sphinx と ReadtheDocs を使用して、ユーザー ドキュメントを GitLab に移行する。
- 古くなった画像や情報を削除します。
- ユーザー ドキュメントを書き直してわかりやすくしました。
- Sphinx 国際化を使用して翻訳できるように設定します。
- ドキュメントをコミュニティ主導型にすることで、ユーザーがドキュメントの閲覧中に発生した問題を報告または解決できるようにします。
このプロジェクトの目的
私は以前から、コードの記述、問題解決、ソフトウェアの構築は、書くことで他の人を啓発する力もあれば、その可能性が最大限に発揮されると考えています。個人的には、VideoLAN コミュニティがマルチメディア向けの無料ソフトウェア ソリューションを作成している取り組みには、いつも感心してきました。VLC メディア プレーヤーは子どもの頃から音楽や映画を観るときにいつも使用していたソフトウェアでした。なぜなら、とても音量が大きく、多くの機能を備えているからです。私の子供時代を素晴らしいものにしてくれたコミュニティと協力できることを光栄に思います。
なぜこのプロジェクトに適任なのか
私がこのプロジェクトに適任である理由は次のとおりです。
- 組織のドキュメントの改善に携わった経験があり、任意のバージョン管理システムを使用できるため、Gitab でコマンドを実行することは問題ありません。それだけではなく、私は人に価値を生むようなプロジェクトに取り組んでくれます。
- 誰かにできるだけ効率的な方法で何かをしてもらいたい場合は、それを文書化するのが一般的です。プロセスを文書化することで、効率性、一貫性、関係者全員の安心感を確保できます。
- 私は VLC ユーザーの一人であるため、VLC ユーザーのニーズを理解しています。これにより、世界中のすべてのユーザーがひと目で理解できるようにドキュメントを作成できるようになります。