A full report of my Google Season of Docs 2020 with CERN-HSF
Modernizing & Restructuring documentation for Rucio
Project Abstract | Phase updates | Final Verdict | Prototype | Resources
Rucio is an open source data management system that has been developed for organizing, managing, and accessing large volumes of scientific data using customisable policies. The framework has documentation that is spread across dockerhub, wikis, scientific articles, Google Drive, and a website hosted on ReadTheDocs with source in the code. There were three major challenges identified -
- Existing documentation had a dependency on the source code
- Disparate sources of documentation had no centralization
- Recent introduction of JSX modules didn't find support in current documentation-as-service tool
The project aims to migrate to a documentation-as-service tool supporting JSX & simplifying the operational support & management of documentation. Additionally, it would eliminate the dependency on source code & centralize the disparate sources by linking them.
The target scope was inclusive of both the technical & qualitative aspects of documentation, thus contributing to a holistic improvement. The endeavour in the qualitative side is to make the user experience & content simpler for folks newer to the technology. The technical aspect mainly deals with migration to a new tool & improving the user interface simpler to navigate & attractive.
Mentors: Martin Barisits, Mario Lassnig, Thomas Beerman
During the Community bonding phase, cadence, agility, & sectioning of the project were the major points of discussion.
-
💭 💬 Cadence: Weekly meetings to be held every Monday at 1.30 PM IST/10.00 AM CEST.
-
🔨Sectioning: The project was divided into phases & sub-phases in order to aid with the agility.
The major phases & sub-phases, per discussion, are as listed below:
- Research & Development (Overlaps with the Community Bonding phase)
- Understanding existing documentation-as-a-service tools
- Gathering requirements
- Researching different tools fitting the requirements
- Prototyping
- Modernizing (Overlaps with the Documentation Development phase)
- Prototyping different themes from UI/UX perspective
- Centralization
- Structuring of documentation
- Qualitative improvements (Overlaps with the Documentation Development phase)
- Fleshing out content structure
- Adding a documentation contribution guide
- Revamping Developer contribution guide
- Finishing design touches
- 🏃 Agility: The agility for each sub-phase was decided to be around a week. Most of the sub-phases overlapped on account of the tasks involved.
Status update for the Community Bonding phase may be found here
Per the sectioning decided in the Community Bonding phase, the status updates for each of the stages involved may be found here.
Final Evaluation Period (November 30, 2020 - December 5, 2020)
During this period, I utilized the progress mentioned here to create a Project Report as also submit feedback about my experience on the program.
Rucio Doc - This is a personal repository containing the source code & the compiled version on GH-pages. Once the prototype has been finalized, the work will be shifted to the documentation repository for Rucio.
The final documentation is now available at: http://rucio.cern.ch/documentation
- Google Season of Docs proposal - Divya Mohan
- Project Link on GSoD website