Проект ЦЕРН-HSF

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:
ЦЕРН-HSF
Технический писатель:
Джон
Название проекта:
CERN-HSF — КОРНЕВАЯ документация для широкой аудитории, динамические привязки Python и учебные пособия
Длина проекта:
Длительный ход (5 месяцев)

Описание проекта

CERN-HSF — ROOT-документация для широкой аудитории, динамические привязки Python и учебные пособия. Наставник: Оливье Куэ, Аксель Науманн

Аннотация: Документация необходима для успешного и эффективного внедрения программного обеспечения пользователями. Ясная, точная и исчерпывающая пользовательская документация помогает пользователям лучше работать с программным обеспечением по мере достижения ими своих целей. В этом смысле подробные примеры и учебные пособия служат мощными инструментами, с помощью которых пользователи могут быстро учиться.

Когда мы изучаем использование ROOT физиками, исследователями и разработчиками в области анализа данных и визуализации физики, мы осознаем преимущества удобной для пользователя и обновленной документации. В частности, из-за широты исходного кода и его роста, система документации может выиграть от параллельного развития, чтобы предоставить пользователям возможность максимально использовать все, что может предложить ROOT.

Сводка и анализ текущей документации В настоящее время пользовательская документация предлагает руководство, которое позволяет физикам легче внедрить ROOT по сравнению с широкой аудиторией. Кроме того, в рамках определенных тем, таких как динамические привязки Python, можно внести улучшения для более полной и понятной документации. Аналогичным образом, новый формат данных RNtuple не имеет необходимых подробных спецификаций. Наконец, в текущей документации отсутствуют учебные пособия, относящиеся к ROOT 7.

Методология: после совещания с Оливье выяснилось, что для решения вышеупомянутых проблем основное внимание должно уделяться выявлению пробелов в знаниях между специализированными исследователями и широкой аудиторией, созданию документации для устранения этого разрыва, написанию более подробной документации по динамическим привязкам Python. , внедрение «учебников по современному анализу» для ROOT 7 и создание подробных технических спецификаций для RNTuple. Таким образом, в ходе этого процесса документация может включать блокноты Jupyter, чтобы материальные и интерактивные инструменты обучения могли помочь пользователям.

Сроки: этапы проекта оцениваются следующим образом: Выявление пробелов в знаниях между специализированными исследователями и широкой аудиторией (при чтении текущей документации и исходного кода) → 1-2 недели Создание и рефакторинг документации для устранения этого пробела → 3 недели Написание более подробная документация по динамическим привязкам Python → 3 недели Внедрение учебных пособий по динамическим привязкам Python → 3 недели Внедрение учебных пособий для ROOT 7 → 4 недели Создание подробных технических спецификаций для RNTuple → 3 недели Обзор целей проекта успешно завершено → 1 неделя

Результаты и рекомендации для достижения успеха: Единая унифицированная пользовательская документация без каких-либо пробелов. Полностью обновленная пользовательская документация, отражающая новейшие функции, например, новые производные классы. Учебные пособия через блокноты Jupyter.