GSOD Project Report: Modernize (rewrite) the VLC user documentation
Subscribe to my newsletter and never miss my upcoming articles
VideoLAN is a non-profit organization that develops software for playing video and other media formats. VLC media player (commonly known as just VLC) is a free and Open Source cross-platform multimedia player and framework that plays most multimedia files as well as DVDs, Audio CDs, VCDs, and various streaming protocols built by the VideoLAN organization and a team of volunteers.
During the Google Season Of Docs program, I worked with the VideoLAN organization on the project - Modernize (rewrite) the VLC user documentation. The original proposal for the project can be found here.
After my proposal was accepted by the VideoLAN organization, my mentors and I agreed on the goals that I was expected to achieve during the Google Season of Docs program. The aforementioned goals can be found below:
- 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 easy to understand.
- Set it up for translation using Sphinx Internationalization.
Community Bonding: Planning the solution
My mentors and I agreed on the right time and channel for communication due to time difference. I refined my goals and set expectations with my mentor and also learned more about the community(VideoLAN) and product(VLC media player). I also had to ensure that the proposed documentation structure I drafted was in line with the goals of the organization so I asked my mentors to vert it and we finalized on the proposed features and modifications that I was supposed to work on.
Documentation Development Phase
Restructuring the VLC user documentation
At the application phase, I drafted a structure describing the proposed VLC user documentation. My intention was to use it as a guide during the implementation phase of the project and just as planned, I started out with using the structure but as I continued working on the documentation, a more user-friendly approach birthed off the first structural draft came to mind and I decided to follow that instead. With this, I implemented the structure here.
The first thing I had to do was to create a repository for the documentation on Gitlab and also add a README file to Gitlab to help future contributors understand how to contribute to VLC's user documentation, then I eventually connected the repository to Read the Docs documentation hosting site. The Gitlab repository can be found here while the readthedocs build can be found here. After I had successfully set up the version control system (Gitlab) and hosting site (Read the Docs), I started writing content for the overview page of the user documentation with Sphinx and created different folders and subfolders for each chapter of the newly structured user documentation. At this point, I was not just able to successfully restructure the documentation, but I also made it easy for future contributors because of the detailed README file I added on Gitlab.
Migrating the documentation to Gitlab using Sphinx and ReadtheDocs
During the documentation phase, I was able to move all existing documentation related to VLC users to Gitlab. To achieve this, I used a robust and mature solution for software documentation called Sphinx.
Sphinx 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. To ensure that every VLC user would be able to easily navigate through the documentation, I used a theme called ReadtheDocs for the VLC user documentation. After my mentor reviewed what I had worked on at this point, he mentioned that he wasn't comfortable with hosting the docs on ReadtheDocs because of all the advertisements on the platform and he advised me to use Gitlab CI configuration. To do this, I used the free pages tool provided by Gitlab to render and publish the documentation by adding a CI configuration to build the sphinx documentation directly from Gitlab. This way, every commit I made to the repository reflected on the site in a couple of seconds. The Gitlab CI pipeline can be found here while the codes used to activate the free pages can be found here.
Updating the documentation to fit modern versions of VLC
In the process of moving the existing VLC user documentation to Gitlab, I read through every line of the documentation, rephrased sentences to make them easy to understand, added more information when necessary and experimented with all the steps to ensure that it matches the current version of VLC and when it didn't, I made the necessary updates to it. This was a continuous process as it happened every day I wrote the documentation because I wanted to ensure that everything was up to date. Aside from this, I also added new content for certain things I couldn't find on the existing documentation.
Removing obsolete images and information
This was an important goal for me so I actually didn't add any image from the existing documentation to the new one. As mentioned in the section above, I tried out everything myself before writing it down which means I took screenshots from the current version of VLC from my windows computer and a friend's Mac os X computer and added it to the documentation.
Rewriting the VLC user documentation
I have been using the VLC media player since I was a child so this part came naturally because I understood what other users want to see in the VLC user documentation. To achieve this I rephrased sentences that I found confusing in the existing documentation. Added new sections that didn't exist like: Tips and Tricks, Support, User Guides, Getting Started, etc. When adding fresh content, I used words that won't be confusing for any user and also created a glossary explaining every complex word.
Set it up for translation using Sphinx Internationalization
Sphinx has a feature that translates documentation manually or through the transifex UI. This was more like research for me because the documentation as not be translated yet at the time of this writing because what I worked is just the first phase of the entire user documentation. More advanced features, contents, images, and explanations will have to be added because the VLC media player is encompassed with a lot of advanced features which has been included yet in the documentation. However, my mentors and I were able to agree on the possible approach to use when it is time to translate the documentation.
The VLC media player is known for its ability to run on all platforms and this meant I had to write a user documentation that would be useful for people using Windows, Linux, Mac, Suse, and other operating systems. It was challenging for me to find people who used these operating systems and even when I found them, getting their laptops for a couple of hours to test the behavior of VLC on work each operating system was quite challenging for me. When I spoke to my mentor about this, he asked me to put more focus on windows for now and work on other operating systems later. At this point, this issue became less challenging.
What did I learn?
I learned a lot more about the VideoLAN organization and VLC during the google season of docs program. I found out that VLC has even more features I never knew about and I was also able to learn how to the Sphinx documentation platform. My technical writing skill has definitely become better.
Overall, It was one of the best things that happened to me this year. I have been using VLC for as long as I can remember and the fact that I was able to contribute to the organization is an honor.
Thanks for rewriting your experience.
Had a question! When to we actually get to share the PDF proposal with the organization like this one which has more details such as our timeline, reason to choose particular org, etc.
Does it happen after proposal getting selected?
Edidiong Asikpo But this time, we were supposed to only write in a good old Google Form, which has limitations as my proposal had tables, etc. I shared link to my PDF proposal though which has more details.
Anyway, Thanks for the reply.