На этой странице содержится подробная информация о проекте технического написания, принятом для участия в 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.