This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- VLC
- Technical writer:
- Abhishek Pratap Singh
- Project name:
- Continue the Modernization of the VLC user documentation
- Project length:
- Standard length (3 months)
Project description
CURRENT STATUS OF THE DOCUMENTATION
The VLC User Documentation is in the process of being modernized and being updated. The transition is in progress to go from the wiki-based older documentation[1] to the sphinx built modern user documentation[2] hosted on ReadTheDocs.
TARGET AUDIENCE
The target audience is both a curious user who wishes to explore the features of the VLC media player beyond an ordinary media player, and to some extent, it will help developers as well by serving as an easy reference guide. Hence, I plan to include both GUI-based instructions (along with images where relevant) and CLI-based methods (along with code snippets) so that the end-user has freedom of choice.
I believe that the language of the documentation (especially the GUI section) should be toned down enough that a person with nominal exposure to operating computers would be able to understand and implement the guide. On the other hand, it shouldn't be too long or explanatory (especially the CLI section) that the coders lose interest.
The right balance can be achieved by mentioning pre-requisites at the start of the page or keeping optional sections that the well-versed can skip.
For building translations, the target audience is developers/users of VLC with a good grasp of English and the language they would be translating to.
TOOLS
The new documentation is being built by Sphinx and hosted on ReadTheDocs, and the version control system is implemented in GitLab. I have had some past experience using Git and GitHub, which helped me in getting a hang of GitLab, although there were certain different features that took some time to learn.
As for Sphinx, I had read about it when a fellow open-source enthusiast had remarked how many organizations are using it for building their documentation (with the notable example of Blender, which uses Sphinx for building their User Manual[3] and API documentation[4]).
I was slightly familiar with ReadTheDocs, which is a good tool for versioning and for hosting technical documentation. Hence, I was able to build VLC documentation without much issue and am familiar with reStructured Text, the formatting used.
For translations, VLC is using Babel to generate .po files in order to implement i18n and l10n. Currently, I am familiarizing myself with Babel workflow and how to build .mo files using Sphinx.
I intend to use the bonding period to further familiarize myself with the intricacies of the above-mentioned tools.
DELIVERABLES AND WEEKLY TIMELINE
As part of the 2019 project, parts of Installation, Interface, Audio, Video, Playback, etc. (most of the basic functionalities) are already covered. Hence, for the 2020 project, I would like to update and work on the advanced usage section of the User documentation.
DELIVERABLE 1 [Week1-2]: Update Transcode Documentation, as mentioned in #7[5].
- Transcode
- Transcode Multiple Videos
- Add a logo
- Merge videos together
- Extract Audio and Extract audio from a file
- Rip a DVD
DELIVERABLE 2 [Week 3-4]: Update Using VLC as a web-plugin[6], while testing in Firefox 77, Chrome 83, and Edge 83.
- Building webpages with video
- Embed tag attributes
- JavaScript API description
DELIVERABLE 3 [Week 5]: Test the Command Line Interface[7] commands and update accordingly.
- Streams
- Modules selection
- Item Specific Options
- Filters
Week 6: Buffer Week for the above three deliverables.
DELIVERABLE 4 [Week 7-8]: Prepare for translations. Apart from updating, I will prepare for translations to other languages. This is important as after translation, users with no English background would be able to read the documentation (and, on a side note, VLC would be a step closer to achieve World Domination[8]).
As mentioned in the Tools section of the proposal, VLC currently uses Babel to generate .po files for translations. I will document the process for a user/volunteer to:
- Download and build the base documentation locally.
- Use Babel to generate the required files.
- Enter Translations for the strings.
- Building the translated documentation using Sphinx.
- Commit the changes.
DELIVERABLE 5 [Week 9-10]: Prepare for modules documentation. As discussed with the mentors, I plan to prepare for modules documentation in two parts.
Part - I: Creating files near to the modules through a script that looks for valid options from the code base and extracts their one-line usage (and default values) from corresponding wiki pages. This would serve as a basic draft.
Part - II: Building a platform-specific structure that links all the modules+plugins+options for a particular platform (Windows, and if time permits, for Fedora as well).
Creating files near the modules will ensure that the documentation is close to the source code. Using a bottom-top approach, the main Modules Documentation would be built from combining the files made in Part - I and using the structure made in Part - II as a reference.
The files created through automation would need a review, but the first priority is to make a functional framework. Once that is achieved, and as per the time available, I would review the files to verify the options. The framework is being prioritized as once it is available, the developers and maintainers can also start contributing by adding relevant use cases.
BONUS DELIVERABLE [Week 11]: Prepare for 4.0 release. In case the project stays on schedule, I would like to propose a bonus deliverable. As discussed with the mentors, preparing for the 4.0 release implies having a stable and almost complete documentation for version 3.0.
Hence, I would go through the already completed documentation of the following sections to verify and update the methods mentioned:
- Basic Usage: Media, Playback, Audio, Video, Subtitles, Hotkeys, Recordings, Settings, Tips & Tricks.
- Advanced Usage: Player, Interface, Transcode, Streaming, Unusual Cases.
- Add-ons: Extensions, Skins.
Week 12: Buffer Week for the above three deliverables + Final Reports.
WHY AM I THE RIGHT PERSON FOR THIS PROJECT?
As a tech enthusiast, I have experience with using/testing software and at times, trying to make sense from their code bases. In fact, trying to understand the code base of an open-source organization was the first time I had truly realized the importance of documentation. Further, as a music enthusiast, I have a lot of experience tweaking around with VLC :)
Apart from that, I’ve been a researcher and writer all my life. Unless I write down something, I never really understand it, and this habit has made me an efficient note-taker and documenter.
The intersection of these two habits is what makes me a right fit for technical documentation. I can find my way through the technical aspects along with documenting my findings/processes in a way that users understand.
Links: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35