На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- ЦЕРН-HSF
- Технический писатель:
- УдачаВДожде
- Название проекта:
- ROOT-документация: анализ, реструктуризация и переписывание
- Длина проекта:
- Длительный ход (5 месяцев)
Описание проекта
Проект состоит из четырех этапов:
1.) Анализ текущей ROOT-документации
Полный ROOT-документ (веб-сайт, руководство пользователя, справочник по C++, учебные пособия и т. д.) анализируется и проверяется по следующим критериям: структурирование, модульность, стандартизация, механизмы доступа, последовательность, используемые типы информации, подготовка для конкретной целевой группы и понятность. Целью является создание концепции управления информацией, матрицы структурирования и руководства по стандартизации содержания.
2.) Определение метода структурирования документации по программному обеспечению с командой ROOT.
DITA (Darwin Information Typing Architecture), стандарт OASIS для документации программного обеспечения ( https://www.oasis-open.org/committees/dita/ ), представлен команде ROOT. Основное внимание уделяется пониманию того, как структурировать контент, специфичный для программного обеспечения, и как элементарные типы информации, такие как «концепция», «задача» и «ссылка», используются для написания документации по программному обеспечению.
3.) Реструктуризация и реорганизация ROOT документации.
На основе результатов первых двух шагов ROOT-документация реструктурируется и модулируется в соответствии с целевыми группами, ролями и вариантами использования, а содержимое распределяется по соответствующим элементам (веб-сайт, руководство пользователя, справочник по C++, учебные пособия и т. д.). и типы контента. Поскольку доступная информация очень обширна, необходимо также создать последовательную справочную структуру. Цель состоит в том, чтобы дать всеобъемлющий обзор и показать пользователям понятные способы использования ROOT для своих нужд. Кроме того, предоставляется компактное введение, не ориентированное на физику.
4.) Переписывание ROOT-документации
Основные части документации, особенно Руководство пользователя, переписаны в соответствии с подходом DITA. Правила структурирования и написания записаны в Руководстве по стилю, чтобы обеспечить единообразие документов в будущем. Цель состоит в том, чтобы дать возможность команде ROOT самостоятельно расширять и поддерживать документацию ROOT в будущем.
Ориентировочный график (5 месяцев):
Этап 1: Анализ текущей документации ROOT: 3 недели.
Этап 2: Определение метода структурирования документации по программному обеспечению с командой ROOT: 2 недели.
Этап 3: Реструктуризация и реорганизация ROOT-документации: 4 недели.
Этап 4: Переписывание ROOT-документации: 11 недель.