VideoLAN project

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:: VideoLAN
Technical writer:: Edidiong Anny Asikpo
Project name:: Modernize (rewrite) the VLC user documentation
Project length:: Standard length (3 months)

Project description

ABSTRACT

A User documentation is designed to assist end users to use a product or service. Good user documentation is very important because it provides an avenue for users to learn how to use a software, its features, tips, tricks and also resolve common problems encountered when using the software. It also reduces support cost and is part of the corporate identity of the product: a good user documentation is a sign of healthiness of the product, the developer team.

Without a good user documentation, a user may not know how to do the above things effectively and efficiently. User Documentations can play a pivotal role in ensuring a product's success because great communication is and will always be at the heart of any business or product and a great documentation just takes that communication and puts it in a manageable framework that everyone can access for success.

At the time of this writing, the VLC user documentation has been accessed 4,634,065 times and the VLC media player is downloaded at approximately 23 million times every month from the main website, this shows that a lot of people all over the world use the VLC Media Player and may want to read its user documentation for guidance on how to use the media player. However, the VLC media player user documentation is currently outdated and incomplete (it was last modified on the 28th day of October 2015) and the VideoLAN community wants to use this project to improve its user documentation to enable end users to have a seamless experience when using the VLC media player.

CURRENT STATE

Currently, the user documentation is available on a wiki page. It is obsolete, incomplete, hard to navigate or find information, does not cover information about the current version of the media player and can only be translated in Deutsch which causes a major setback for people who can't read the English Language.

WHY IS MY PROPOSED USER DOCUMENTATION AN IMPROVEMENT OVER THE CURRENT ONE?

The proposed user documentation will be structured to improve and ensure efficiency, consistency, and peace of mind for an end user. It will contain written guides and its associated images, include instructions and explanation on how to use each feature of the VLC media player, up to date, easy to navigate, understandable and translatable in at least five major languages.

Mentors: Jean-Baptiste, Alex, Simon

ANALYSIS

Jean-Baptiste and I had a conversation about the new environment that the current user documentation would be migrated to for improvements and he shared two links that showed a Gitlab repository of the source file written with Sphinx and the main documentation hosted on Read the Docs and he said they expect the new documentation to be similar to it. I researched a lot about these tools to get a better understanding of how it works.

Sphinx

Sphinx is a robust and mature solution for software documentation. It includes a number of features that writers expect, such as single source publishing, content reuse through includes, conditional includes based on content type and tags, multiple mature HTML themes that provide a great user experience on mobile and desktop, referencing across pages, documents, and projects Index and Glossary support and internationalization support. It also uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its ability to translate documentation.

Read the Docs

Read the Docs simplifies software documentation by automating building, versioning, and hosting of your docs for you. It never goes out of sync; that is, whenever you push code to your favorite version control system, whether that is Git, Mercurial, Bazaar, or Subversion, Read the Docs will automatically build your docs so your code and documentation are always up-to-date. It has multiple versions; Read the Docs can host and build multiple versions of your docs so having a 1.0 version of your docs and a 2.0 version of your docs is as easy as having a separate branch or tag in your version control system. Read the Docs is free and open source and hosts documentation for nearly 100,000 large and small open source projects in almost every human and computer language.

VERDICT

Sphinx is an incredibly powerful tool and Read the Docs builds on top to provide hosting for Sphinx documentation that keeps your docs up to date across versions. Together, they are a wonderful set of tools that developers and technical writers can use to create user documentation that would be best for end users.

Sphinx includes support for translating documentation into multiple languages. It supports version control which will be used to manage the documentation. Unlike the current wiki where anyone can edit and not add the right information, this version control system would ensure that all changes are reviewed first before it is merged to the main repository. Version control will also make the documentation increase open source contribution to the project because people can create issues, open pull requests, etc. Sphinx and read the Docs is used by a list of other great and communities such as; ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs, etc and it is a great tool to use for the new VLC user documentation.

I didn't just read about these tools, I also created a basic sample. This is the link: https://gitlab.com/Didicodes/demo-vlc-user-documentation to my Gitlab repository while the hosted version on readthedocs can be found here: [https://vlc-user-documentation-demo.readthedocs.io/en/latest/](https://vlc-user-documentation-demo.readthedocs.io/en/latest/.

STRUCTURE OF THE PROPOSED DOCUMENTATION

I created a structure for the VLC User Documentation which can be found here; https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. Before the implementation of this new structure begins, it has to be approved by the mentors. This means that the structure is likely to change after it has been reviewed by the mentors.

PROJECT GOALS

Restructure the documentation.
Update the documentation to fit the modern versions of VLC.
Migrate the user documentation to Gitlab using Sphinx and ReadtheDocs.
Remove obsolete images and information.
Rewrite the user documentation to make it easier to understand.
Set it up for translation using Sphinx Internationalization.
Make the documentation community driven so that users can report or solve any issues encountered while reading the documentation.

WHY THIS PROJECT?

I have always had a conviction that writing code, solving problems and building software reaches its full potential when you also have the ability to enlighten others about it through writing. Personally, I have always been fascinated by the efforts undertaken by the VideoLAN community in creating free software solutions for multimedia. Growing up as a child, the VLC media player was always the software I used when listening to music or watching a movie because it was very loud and consisted of so many features. It will be an honor to work with the community that contributed to making my childhood awesome.

WHY AM I THE RIGHT PERSON FOR THIS PROJECT

I believe I am the right person for this project because:

I have past experience in improving the documentation of organizations and I can use any version control system, so carrying out commands on Gitab will not be a problem. Moreover, what drives me is working on projects that create value for people.
I believe that If you want someone to do something in the most efficient way possible, you document it. By documenting your processes, you ensure efficiency, consistency, and peace of mind for anyone involved.
I know the needs of VLC users because I am one of them. This will enable write the documentation in such a way that every other user across the globe understands at first glance.