このページは Cloud Translation API によって翻訳されました。

VideoLAN プロジェクト

このページには、Google シーズンのドキュメントで受け入れられているテクニカルライティングプロジェクトの詳細が記載されています。

プロジェクトの概要

オープンソースの組織:: VideoLAN
テクニカルライター:: Edidiong Anny Asikpo 氏
プロジェクト名:: VLC ユーザードキュメントをモダナイズ（書き換え）
プロジェクトの期間:: 標準の期間（3 か月）

プロジェクトの説明

概要

ユーザードキュメントは、エンドユーザーがプロダクトやサービスを利用できるようにするためのものです。優れたユーザードキュメントは、ソフトウェアの使い方や機能、ヒント、コツを学び、ソフトウェアを使用する際に発生する一般的な問題の解決方法をユーザーに教える手段になるため、非常に重要です。また、サポート費用も削減でき、プロダクトのコーポレートアイデンティティの一部となります。優れたユーザードキュメントは、デベロッパーチームであるプロダクトの健全性の証です。

適切なユーザードキュメントがなければ、ユーザーは上記のことを効果的かつ効率的に行う方法がわからない可能性があります。ユーザードキュメントは、プロダクトを成功に導くうえで極めて重要な役割を果たします。優れたコミュニケーションは、あらゆるビジネスやプロダクトの中心であり、これからもそうであるからです。優れたドキュメントは、そのようなコミュニケーションを取り、誰もがアクセスできる管理しやすいフレームワークにまとめます。

本稿執筆時点で、VLC ユーザードキュメントには 4,634,065 回アクセスされており、VLC メディアプレーヤーはメインのウェブサイトから毎月約 2,300 万回ダウンロードされています。これは、世界中の多くの人が VLC Media Player を使用していることを示しています。メディアプレーヤーの使い方についてはユーザードキュメントを確認することをおすすめします。しかし、VLC メディアプレーヤーのユーザードキュメントは現在古くなっておらず（最終更新日: 2015 年 10 月 28 日）、VideoLAN コミュニティはこのプロジェクトを使用して、エンドユーザーが VLC メディアプレーヤーをシームレスに使用できるようにユーザードキュメントを改善したいと考えています。

現在の状態

現在、ユーザードキュメントは Wiki ページで入手できます。情報が古く、不完全で、操作や情報の検索が難しく、メディアプレーヤーの現在のバージョンに関する情報も記載されていません。また、ドイツ語でしか翻訳できないため、英語を読めないユーザーにとっては大きな不満となります。

私の提案されたユーザードキュメントが現在のドキュメントより改良されたのはなぜですか？

提案するユーザードキュメントは、エンドユーザーにとって効率、一貫性、安心感を改善し、保証するために構成されます。文書内のガイドと関連画像を含み、VLC メディアプレーヤーの各機能の使用方法の説明と説明も含みます。最新の最新で操作しやすく、理解しやすく、少なくとも 5 つの主要言語に対応しています。

メンター: ジャンバプティスト、アレックス、サイモン

分析

Jean-Baptiste と私は、改善のために現在のユーザードキュメントを移行する新しい環境について話し合ったところ、Sphinx で記述されたソースファイルの GitLab リポジトリと Read the Docs でホストされているメインドキュメントを示した 2 つのリンクを共有してくれました。その仕組みをよく理解するために、こうしたツールについていろいろ調査しました。

スフィンクス

Sphinx は、ソフトウェアドキュメント向けの堅牢で成熟したソリューションです。これには、単一ソース公開、インクルードによるコンテンツの再利用、コンテンツタイプとタグに基づく条件付きインクルード、モバイルとパソコンで優れたユーザーエクスペリエンスを提供する複数の成熟した HTML テーマ、ページ、ドキュメント、プロジェクト間での参照、インデックスと用語集のサポート、国際化のサポートなど、ライターが期待する多くの機能が含まれています。また、マークアップ言語として reStructuredText を使用しています。その強みの多くは、reStructuredText のパワーとわかりやすさ、ドキュメントの翻訳機能にあります。

ドキュメントを読む

ドキュメントを読むでは、ドキュメントの作成、バージョニング、ホスティングを自動化して、ソフトウェアドキュメントを簡素化できます。同期が失われることはありません。つまり、Git、Mercurial、Bazaar、Subversion など、お気に入りのバージョン管理システムにコードを push するたびに、Read the Docs は自動的にドキュメントを作成しているため、コードとドキュメントは常に最新の状態になります。複数のバージョンがあります。「ドキュメント」では、ドキュメントの複数のバージョンをホスト、ビルドできるため、バージョン管理システムで別のブランチやタグを使用するのと同じくらい簡単に、ドキュメントの 1.0 バージョンと 2.0 バージョンを使用できます。Read the Docs は無料のオープンソースであり、ほぼ 10 万件の大小さまざまなオープンソースプロジェクトのドキュメントをほぼすべての人間とコンピュータの言語でホストしています。

確認

Sphinx は非常に強力なツールです。また、Read the Docs を基盤とし、Sphinx のドキュメントをホストしてバージョン間で常に最新の状態に保ちます。この 2 つを組み合わせると、デベロッパーとテクニカルライターがエンドユーザーに最適なユーザードキュメントを作成するための優れたツールセットになります。

Sphinx は、ドキュメントを複数の言語に翻訳する機能をサポートしています。また、ドキュメントの管理に使用するバージョン管理をサポートしています。誰もが編集できるが、正しい情報を追加できない現在の Wiki とは異なり、このバージョン管理システムでは、すべての変更がメインリポジトリにマージされる前に、まずレビューされます。また、バージョン管理により、イシューの作成や pull リクエストのオープンなどが可能になるため、ドキュメントのオープンソースへの貢献も増えます。Sphinx と read は、ASP.NET、Kernel、Julia、Jupyter、PHPMyAdmin、Write the Docs など、他の多数のコミュニティやコミュニティによって使用されており、新しい VLC ユーザードキュメントに使用するのに最適なツールです。

これらのツールについて学んだだけでなく、基本的なサンプルも作成しました。私の GitLab リポジトリへのリンクは https://gitlab.com/Didicodes/demo-vlc-user-documentation です。また、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 メディアプレーヤーは子供の頃、音楽を聴いたり映画を見たりするときに常に使っていたソフトウェアでした。なぜなら、VLC はとてもうるさくて、多くの機能で構成されていたからです。子供の頃を素晴らしいものにするために貢献してくれたコミュニティと協力してできることを光栄に思います。

私がこのプロジェクトに適している理由

以下の理由から、私がこのプロジェクトの担当として適任であると考えております。

過去には組織のドキュメントを改善した経験があり、どのバージョン管理システムでも使用できるため、Gitab でコマンドを実行しても問題はありません。そのうえ、人々に価値を創造するプロジェクトにも力を入れています。
できるだけ効率的なやり方で誰かに何かをしてほしいなら、それは記録するべきだと思います。プロセスを文書化することで、効率と一貫性を確保し、すべての関係者に安心感を与えることができます。
私も VLC ユーザーのニーズはよくわかります。これにより、世界中のすべてのユーザーが一目で理解できるようにドキュメントを作成できます。