Modernize the Rucio documentation

Documentation has been cited as one of the key factors along with established policies towards the adoption of Open-Source software packages. With the industry projected to cross $33 billion by 2022, the role that technically & qualitatively sound documentation assumes is only set to gain more importance.

In the second cohort of Season of Docs this year, the program saw an acceptance of nearly double the number of writers as compared to the premier season in 2019. As one of the participants who was selected in this year’s program, I read through a lot of great blogs (like here and here) before applying. I wanted to contribute to the existing excellent content by sharing my thoughts on how to have an (almost) smooth-sailing experience on the program.

Step 1: Read (No, actually READ!) through the project descriptions

I know it does seem like an obvious & unnecessary first step. However, read through each of the project descriptions before you choose! You’ll be committing a fair amount of time & energy to this program over the next three months (five, if you’re selecting a longer duration project). Aligning your interests/strengths with a particular project helps maintain motivation levels in the long run. Therefore, it is absolutely essential you read through the descriptions & understand exactly what is being expected of a technical writer for that particular project.

Step 2: Communicate, Communicate, Communicate!

Should you have any queries in step #1, most organizations post the Slack/Gitter channel & email IDs of the mentors for potential participants to reach out. Use all avenues available to ensure that both you and the participating organization are able to benefit maximally. Prior to the program, it is also a great idea to start contributing to the project (if allowed). This will give you a fair idea of how the project is structured & what the working environment will be like, if you get selected.

Post selection, of course, the community bonding phase allows you to get acclimatized to the project. However I found it very helpful when one of my mentors, Martin, set guidelines around how we communicated & the frequency of our project meetings. It enabled me to section my work into chunks throughout the week & keep my mentors in the loop throughout. (Thank you, Martin!)

Step 3: Structure your work

As a Senior Systems Administrator with HSBC in my day job & an active contributor to multiple Open-source projects, I cannot emphasize how important it is to section the work you’re going to do. Understanding what the goals & outcomes were at the start & end of each phase helped me divide time between various commitments. Fortunately since all of us were on the same page regarding this particular step, it was easier to have a conversation about this. I’ve documented a progress report of-sorts in this public GitHub repository.

Step 4: Have fun!

Documentation need not always be dreary & boring! While transitioning the documentation from the existing ReadTheDocs setup to a more centralized model, especially, during a pandemic it was extremely easy to forget I was doing something I loved - writing & tinkering! Speaking with other participants, learning from them, and presenting my learnings at conferences were extremely helpful in cementing my knowledge. This, of course, might not be your idea of fun (and that’s totally understandable!). However, the key takeaway would be to enjoy the process while keeping your project goals in sight.

Prior to the program, I wasn’t aware of how exascale data management systems like Rucio (or its predecessor DQ2) worked. I learned a lot just by structuring the documentation & going through the code base that Sphinx built its documentation from.

My technical skills have improved tremendously over the course of this program. I would be remiss if I did not express my gratitude to the admin team & my mentors - Martin Barisits, Mario Lassnig, & Thomas Beerman for all their support throughout. Participating in the Google Season of Docs was definitely one of the highlights for me in 2020!