This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- CERN-HSF
- Technical writer:
- John
- Project name:
- CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials
- Project length:
- Long running (5 months)
Project description
CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials Mentor: Olivier Couet, Axel Naumann
Abstract: Documentation is essential for successful and efficient software adoption by users. Clear, accurate, and comprehensive user documentation facilitates users’ proficiency with the software as they strive towards their goals. Along those lines, explicit examples and tutorials serve as powerful tools by which users can quickly learn.
As we examine the use of ROOT by physicists, researchers, and developers within the data analysis and visualization space for physics, there is a recognition of the benefits of user-friendly and updated documentation. In particular, due to the breadth of the source code and its growth, the documentation system stands to benefit from parallely evolving in order to grant users the ability to maximize all that ROOT has to offer.
Summary & Analysis of Current Documentation Currently, the user documentation offers a guide that allows physicists to adopt ROOT more easily relative to a general audience. Furthermore, within certain topics such as Dynamic Python Bindings, improvements could be made for more comprehensive and clear documentation. Similarly, the new data format RNTuple is lacking necessary detailed specifications. Finally, the current documentation is missing tutorials related to ROOT 7.
Methodology: After conferring with Olivier, it appeared that in order to address the aforementioned issues, the primary focus should involve identifying knowledge gaps between specialized researchers and a general audience, creating documentation to bridge that gap, writing a more detailed documentation of Dynamic Python Bindings, implementing “tutorials for modern analysis” for ROOT 7, and creating detailed technical specifications for RNTuple. Along those lines, during this process, the documentation could incorporate Jupyter notebooks so that tangible and interactive learning tools can help users.
Timeline: The stages for the project are estimated to be: Identify knowledge gaps between specialized researchers and a general audience (while reading through the current documentation and source code) → 1-2 weeks Create and refactor documentation to bridge that gap → 3 weeks Write a more detailed documentation of Dynamic Python Bindings → 3 weeks Implement tutorials for Dynamic Python Bindings → 3 weeks Implement tutorials for ROOT 7 → 4 weeks Create detailed technical specifications for RNTuple → 3 weeks Review project objectives have been successfully completed → 1 week
Deliverables & Guideline for Success: Singled unified user documentation without any gaps Completely updated user documentation to reflect most recent features, i.e. new derived classes Tutorials through Jupyter notebooks