For Google’s Season of Docs – 2019, the project „ROOT Documentation: Analyze, Restructure and Rewrite“ 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.
Short description of the work done
The project consisted of 4 phases:
- Analyzing the current ROOT documentation.
- Defining a method for structuring a writing software documentation with the ROOT team.
- Restructuring and reorganization of the ROOT documentation.
- Rewriting the ROOT documentation.
With the rework of the ROOT documentation, also the entire ROOT website (https://root.cern.ch/) was to be redesigned and reworked.
Analyzing the current ROOT documentation
A central part of the ROOT documentation was the User Guide. In addition, there are and were numerous other documents such as How Tos, Get Started und Primer documents, Topical Manuals, Tutorials, Courses and last but not least the ROOT Reference Guide. Thus, analyzing meant not only defining the structure for a single document, i.e. the new ROOT Manual to be created, but defining the structure for the entire ROOT documentation.
Defining a method for structuring a writing software documentation with the ROOT team
In order to obtain a more consistent structure for the documents, especially for the text to be written, I suggested DITA (Darwin Information Typing Archtecture) as an approach for writing and structuring the documents. The real challenge in writing the ROOT Manual was to implement the structure of DITA and its separation of information types (task, concept, reference) with Markdown.
Restructuring and reorganization of the ROOT documentation
The aim of the restructuring of the ROOT documentation was to make the information in the documents available as required by the user. Many old structures were abandoned and new concepts developed. Particular importance was attached to the interlocking of the ROOT Manual with the ROOT Reference Guide, in which the ROOT classes are primarily described. The previous monolithic blocks of information were brought together.
Rewriting the ROOT documentation
The ROOT Manual has been restructured and written from scratch. Thanks to the great work of my mentor, it contains many, often interactive examples, so you can start interacting with ROOT right away. I also helped the ROOT team to find a suitable structure for the new website in order to integrate the ROOT Manual and the installation instructions for ROOT.
The documentation that was developed
The new ROOT website is still under development, but the date for the launch is coming soon.
The ROOT Manual is currently available at https://root-project.github.io/web/manual/
The download and installation instructions are currently available at https://root-project.github.io/web/download/
Both links will change after the going live of the new website.
Summary of the project
With the new ROOT Manual not only large parts the documentation for ROOT has been newly written, but also the way how the documentation will be created in the future has been changed. With the completed version of the ROOT Manual a up-to-date documentation is now available, which enables the user to get a faster and practice-oriented introduction to ROOT. The connection with the ROOT Reference Guide allows quick access to the essential information.
Challenges and learnings
If an organization is not satisfied with its technical documentation, it is often thought, according to Lev Tolstoy, that all good documentation is similar, but each bad documentation is bad in its own way. But often the opposite is the case. Therefore, it is not difficult to rewrite the bad (or, to put it more nicely, the non-user friendly) documentation. All the ingredients that make a technical documentation difficult are usually always the same.
But here the challenge was the amount of information. Just as ROOT is used to analyze petabytes of data from LHC (Large Hadron Collider) experiments, there is also an almost unmanageable amount of information available on ROOT. The Reference Guide alone requires about 700 MB (a compressed file!) for the download.
Anyone who starts to deal with ROOT is exposed to this immense amount of information. The natural question is then of course: Where should I start? To answer this question and to show a praticable way for using ROOT was the big task. I hope that everyone will now find it easier to take advantage of the fantastic opportunities that ROOT offers.