CERN-HSF project

This page contains the details of a technical writing project accepted for 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.