GSoD’20 Final Project Report: Continue the Modernization of the VLC User Documentation
Open Source Organization: VideoLAN
Project: Continue the Modernization of the VLC User Documentation
Overview
VideoLAN is a non-profit organization that produces and distributes free and open source software for video and multimedia purposes. It is responsible for developing and maintaining the VLC Media Player (which I’m sure almost everyone reading this must have already used ;)
VLC is a free and open source cross-platform media player that prides itself for being one of the few media players that can play almost all multimedia files, as well as DVDs, Audio CDs, VCDs, and various streaming protocols.
The VLC User Documentation is in the process of being modernized, restructured, and transitioned from wikis to being hosted on ReadTheDocs. My project was to continue the modernization, and as was mentioned in the original proposal, the aim was to document some of the advanced features of VLC that make it so much more than an ordinary media player.
The Community Bonding Phase
In this phase, many internal meetings were conducted to decide how to proceed with the documentation. I got to bond with my mentors and other technical writers. It was decided that the modernized documentation should be more user focused (and hence most of the files have been created with the intent of answering the “how to” questions). I also used this time to explore features certain of VLC and acquainted myself with its command line usage.
The Document Development Phase
We started the documentation process by working on explaining how the “sout” chain works as a pipeline, and how the individual modules interact with each other to perform an operation.
From there, the project branched into two topics (streaming and transcoding). In the last month, we decided to start working on updating the documentation for VLM (VideoLAN Manager) as well.
As the topics we worked upon are quite huge, there is a lot of future scope. For streaming, transcoding, and VLM, the future scope is mainly covering interesting use cases.
Following is the status of the project as of writing this report:
This issue points to all the relevant Merge Requests, and is used for keeping track of all the contributions. The content of the MRs is still being discussed upon and hence it has not been merged yet.
Further, these are the relevant Issues (#1 to #6) containing all the discussions that happened over them.
I had started working on a few of the topics in the “Future Scope” section, but I think the contributions for those files can now only be made outside the scope of the GSoD project. They are a part of my To-Do list to be done after the program ends :)
Challenges
An expected challenge was the learning curve. Before this project I had no idea about how protocols like RTP, SAP, or RTSP work. I also didn’t really know how codecs and muxers relate to each other when we need to transcode.
However, I received excellent guidance from my mentors and with a combination of their explanations, researching over the internet, trying different things on my own, and getting my doubts cleared from them, I was able to grasp how things are actually working. (On a side note, this is the reason why I’m really interested to work on the “Under the Hood” documentation, but I couldn’t make the time for that).
On a personal front, one challenge that I faced was time management. Because of covid, my Bachelor Thesis Project (BTP) was unexpectedly shifted to be done in Aug-Oct. When I was applying for GSoD in June, I was expecting that the BTP would take place in 2021, and hence I hadn’t factored the time that I would have to commit to it.
But because I got aware about this issue in July itself, I decided to use the Bonding Phase to explore how to operate VLC from the Command Line, which eventually helped a lot in the project as most of the advanced features rely on the CLI. Moreover, being at home instead of the hostel also saved a significant amount of time and hence I was able to balance.
Experience and Learnings
I have had the opportunity to explore quite some interesting features in the past few months and the entire journey has been nothing short of a fascinating learning experience. The best part about documenting the features is implementing and testing them.
I also learned a lot about what a good documentation is all about. For example, the use case of “how to share screen in real time using VLM” was one of the last things I worked upon in November. It incorporated almost everything that I learned in the past three months, as it combines the concepts of streaming, transcoding, and configuring the VLM.
And while someone who who has played around with the feature can write the code and run the vlm file from the terminal, the feature can also be easily implemented in just a few clicks by someone who is entirely new to these concepts.
And this encapsulates the very spirit of software — that it is not just for the tech enthusiasts but for the novices as well. That at the end of the day, the aim of documentation is not just to tell how to make something work to those who are familiar with the underlying technology.
I have learned that apart from providing a precise guide, another important objective of a good documentation is to help someone with only a little experience in implementing these features. And then, if the user is still curious, a good documentation provides them with a way to learn about how things are working so that they can tweak around and customize it to their specific systems and their specific needs.
Hence, one of my biggest takeaways is that along with answering the “how to” questions, a good documentation also helps in making an experimenter out of a curious user.
Apart from learning about VLC and Documentation, I learned about how to better use tools like GitLab and Sphinx. I also learned how to use Graphviz, which is an incredibly useful tool for documentation because of its consistency and maintainability.
Word of Thanks
I would like to thank my Mentors, Alexandre Janniaux and Simon Latapie. They have been extremely helpful all along the way. When the project started I was a little worried thinking “what if my knowledge gaps become a hindrance?”
However, that did not happen because both Simon and Alex have been extremely helpful — from explaining the nuances of how things are actually working to clearing my doubts. They have both been really kind, considerate, and have always encouraged me to ask questions whenever I get stuck somewhere.
I would like to thank all the members of VideoLAN, especially Jean-Baptiste Kempf, the President at VideoLAN, and François Cartegnie, who helped in solving a few of my queries. I would also like to extend my heartiest congratulations to Avinal Kumar, my fellow technical writer who worked on Creating the VLC User Documentation for Android.
Final Thoughts
We have all been affected in one way or another by the ongoing pandemic, and things are still uncertain as the world is navigating its way out of it. As with most of us, my summer was pretty gloomy too, however, the autumn brought with itself a few reasons to smile.
On a personal level, getting selected for the program was one of the very few good things that happened to me this year. An opportunity like this is something one always cherishes, but an opportunity like this in the backdrop of a year like 2020 is something I feel much more grateful for :)
As a tech enthusiast who is equally awe-struck by the power of words as by the power of code, technical documentation is that little area where both my interests intersect. Which is why I think that although this is the end of the Season of Docs ’20, it is just the beginning of my open-source (and my technical documentation) journey, and for that I will always be grateful to VLC and Google.
Au revior :)
