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.