CERN-HSF project

  • This Google Season of Docs project focuses on analyzing, restructuring, and rewriting the ROOT documentation for improved usability and maintainability.

  • The project involves a four-phased approach: analyzing existing documentation, defining a structuring method using DITA, restructuring and reorganizing content, and rewriting key documentation sections.

  • The project aims to create a user-friendly and consistent documentation experience for ROOT by implementing clear structuring principles, modularization, and a comprehensive style guide.

  • This long-running project, spanning five months, collaborates with the CERN-HSF organization and is spearheaded by technical writer LuckInTheRain.

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:
ROOT Documentation: Analyzing, Restructuring and Rewriting
Project length:
Long running (5 months)

Project description

The project consists of four phases:

1.) Analyzing the current ROOT documentation

The complete ROOT document (web site, users’ guide, C++ reference, tutorials etc.) is analyzed and checked according to the following criteria: structuring, modularization, standardization, access mechanisms, consistency, information types used, target group-specific preparation and comprehensibility. The aim is to create a concept for information management and a matrix for structuring and a guideline for standardizing the content.

2.) Defining a method for structuring a writing software documentation with the ROOT team

DITA (Darwin Information Typing Architecture), an OASIS standard for software documentation (https://www.oasis-open.org/committees/dita/) is presented to the ROOT team. The main focus is on understanding how to structure software-specific content and how elementary information types as “concept”, “task” and “reference” are used for writing software documentation.

3.) Restructuring and reorganization of the ROOT documentation

Based on the results of the first two steps, the ROOT documentation is restructured and modularized according to target groups, roles and use cases and the contents are assigned to the corresponding elements (web site, users’ guide, C++ reference, tutorials etc.) and content types. Since the available information is very extensive, also a consistent reference structure must be established. The aim is to give a comprehensive overview and to show users clear ways how they can use ROOT for their needs. In addition, a compact non-physics oriented introduction is provided.

4.) Rewriting the ROOT documentation

Main parts of the documentation, especially the Users’ Guide, is rewritten in accordance with the DITA approach. The structuring and writing rules are recorded in a Style Guide in order to ensure consistency in the documents in the future. The goal is to enable the ROOT team to extend and maintain the ROOT documentation themselves in the future.

Estimated time schedule (5 months):

Phase 1: Analyze the current ROOT documentation: 3 weeks.

Phase 2: Defining a method for structuring a writing software documentation with the ROOT team: 2 weeks.

Phase 3: Restructuring and reorganization of the ROOT documentation: 4 weeks.

Phase 4: Rewriting the ROOT documentation: 11 weeks.