For Google’s Season of Docs – 2020, the project „Extending and improving the ROOT documentation“ was conducted at CERN-HSF.
ROOT is an object-oriented framework that provides all the functionalities needed to deal with big data processing, statistical analysis, visualization and storage in high-energy physics (The Higgs boson was found with ROOT!) .
Short description of the work done
The ROOT documentation should be improved and supplemented in the following areas:
- The ROOT documentation should become more accessible and understandable for non-physicists (the introductory chapters and with supporting texts).
- Some new topics and developments shall be included in the ROOT documentation with detailed descriptions and examples.
- Answers to important questions from users, such as those posted in the ROOT Forum, will be included in the documentation.
- Tutorials explaining the general functionality of ROOT shall be developed.
Making the ROOT documentation more accesssible
As it turned out, even for physicists it is not easy to deal with ROOT. Especially the beginning is difficult. Therefore, the focus was set on making the first steps with ROOT as easy as possible for non-ROOT users. The goal was to enable the reader (in the majority physicists) to use ROOT immediately for his daily scientific work. Thus, other user groups were only considered to a limited extent.
Add new topics that reflect current developments in ROOT
ROOT is a software that has to fulfill constantly new requirements for scientific work. Therefore new developments are constantly taking place, which have to be considered in the ROOT documentation. This task has been consistently and continuously performed in this project.
Older content has been reviewed for accuracy and revised or removed as necessary.
Answering questions from users
The ROOT Forum is the central place for questions about ROOT. Statistics have been compiled and evaluated to identify the most common problems of users with ROOT. Numerous answers to the questions were incorporated into the ROOT Manual. Care was taken to ensure that the relevant content can be found easily.
Instead of tutorials, how-to’s were included in the ROOT documentation, also based on the evaluated statistics from the ROOT Forum. Furthermore, older sources were examined to determine which content should be included in the ROOT Manual. The number of code examples has been increased to handle typical tasks faster.
The documentation that was developed
The ROOT Manual is available at https://root.cern/manual/
Summary of the project
The ROOT Manual has been extensively expanded and focused more on the questions and needs of the users. Numerous sources (old and new) were used, which were integrated into the ROOT Manual in different ways. The connections to the Reference Guide were significantly improved and expanded .Also a new workflow has been established that allows multiple authors to contribute to the ROOT Manual. A review process enables quality assurance.
The result of the project is a manual that is up to date and accepted by the users.
Challenges and learnings
In a large project like ROOT, excellent communication is a key element to ultimately produce not only good software, but also a good manual. Therefore, the most important task is to make sure that communication between all parties involved works well. Due to the outstanding support of my mentor, I was always able to work on the project tasks efficiently. With such a team, physics and technical documentation is fun!
I am proud to continue to be a member of the ROOT team and that I can continue to support it.