CERN-HSF project

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:
LuckInTheRain
Project name:
Extending and improving the ROOT documentation
Project length:
Long running (5 months)

Project description

The project has the goal of improving the documentation of ROOT, which is the main software system for data analysis and data presentation used by the high-energy physics community world-wide.

Besides the technical writer skills that I can provide for the project, I am also familiar with ROOT (6 & 7) and I have knowledge of other components required by the project, such as:

  • C++
  • Python
  • Git/GitHub
  • Web site construction tools (html, markdown, Jekyll)

I identify three main pieces in the ROOT documentation:

  • the web site https://root.cern,
  • the C++ class reference guide https://root.cern/doc/master/,
  • the forum https://root-forum.cern.ch

Seems to me the ROOT documentation (the new "ROOT manual") need to be improved and supplemented in the following areas:

  • It should become more accessible and understandable for non-physicists in particular the introductory chapters.
  • More tutorials explaining the general functionality of ROOT shall be developed.
  • Some new topics and developments shall be included with detailed descriptions and examples. Among those I can list:
    • The Python binding
    • The mathematical libraries
    • Manual description for high level graphics tools (TRatioPLot, THStack)
    • The new data mining analysis tools (RDataFrame and RNtuple)
  • The new key data formats (RDataFrame and RNtuple) need detailed technical specifications and tutorials.

  • Answers to important questions from users, such as those posted in the ROOT forum, will need be included in the documentation. This requires a fine analysis of the most often asked questions followed by a synthesis period to translate them into pieces of documentation in the new "ROOT Manual" or in new some tutorials in the Reference Guide.

  • Tutorials illustrating the functionalities provided by ROOT 7.

    • New ROOT 7 histograms
    • New ROOT 7 graphics

Estimated time schedule (5 months):

  • Phase 1: Definition of tasks and scope for ROOT documentation and tutorials: 2 weeks.
  • Phase 2: Gather and analyse important users' questions from the ROOT forum: 2 weeks
  • Phase 3: Writing ROOT documentation: 8 weeks.
  • Phase 4: Developing tutorials: 8 weeks

Finally I should add that I have already contributed to the ROOT documentation last year with a long-term Google Season of Docs project. I defined the new structure of the Manual. The proposal this year will contribute to the completion of other documentation aspects still missing in ROOT.