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

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

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

Организация с открытым исходным кодом:
ЦЕРН-HSF
Технический писатель:
Ариадна
Название проекта:
Ручио – модернизировать (реструктурировать и переписать) документацию Ручио.
Длина проекта:
Стандартная продолжительность (3 месяца)

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

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

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

На момент написания этой статьи структура Ручио использовалась для обеспечения высокоэнергетических потребностей экспериментов ATLAS и CMS на БАКе. Он также используется для поддержки потребностей различных научных сообществ за пределами LHC, таких как астрофизика; тем самым необходимо, чтобы документация была как можно более актуальной и доступной. С помощью этого проекта ЦЕРН хочет предоставить конечным пользователям Rucio возможность беспрепятственного использования платформы, предоставляя централизованное представление для доступа ко всей соответствующей документации.

Текущее состояние: на сегодняшний день пользовательская документация разбросана по разным местам и представлена ​​в различных форматах, включая научные статьи, readthedocs.io с исходным кодом, Google Drive, GitHub, DockerHub или Wiki. Множественные источники создают проблемы с отслеживанием версий и правильностью документации. Кроме того, децентрализованная модель документации создает значительные препятствия для навигации и предоставления соответствующей информации для конкретного варианта использования. Информация, предоставленная для конкретного эксперимента, особенно в случае с Wiki, вполне может быть применима и к другим экземплярам, ​​находящимся в тех же/других источниках. Однако из-за отсутствия консолидации и соответствующих связей эта информация остается бездействующей и, возможно, недостаточно используемой.

Почему предлагаемая вами пользовательская документация лучше существующей? Учитывая многогранную проблему, предложенная ниже модель устраняет препятствия с навигацией, управлением версиями, отслеживанием и отображением документации, как подробно описано ниже:

Реструктуризация документации направлена ​​на упрощение усилий, затрачиваемых на навигацию для конечного пользователя. Ему/ей не нужно рыться в кроличьих норах в поисках информации, поскольку для простоты они будут классифицированы/маркированы. С административной точки зрения управление версиями и отслеживание будет упрощено, поскольку реструктуризация предоставит свободу категоризации на основе требований. Централизация всей реструктурированной документации позволит гарантировать, что вся информация будет видна пользователю без необходимости обращаться к нескольким источникам.

Анализ: После прочтения краткого описания требований и беседы с командой наставников мои выводы о текущем состоянии документации Ручио следующие:

Существует шесть основных источников документации: - Ссылка на Google Диск: https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7.

  • Readthedocs на базе Sphinx с исходным кодом. Ссылка на код: https://github.com/rucio/rucio. Ссылка на ReadtheDocs: https://rucio.readthedocs.io/en/latest/.

  • Ссылка на DockerHub: https://hub.docker.com/u/rucio

  • Ссылка на GitHub: https://github.com/rucio/rucio

  • Ссылка на вики: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing.

  • Ссылка на научные статьи: https://arxiv.org/abs/1902.09857

Документация в этих источниках представлена ​​в разных форматах. Например, на Google Диске есть документация в виде слайдов и документов, на GitHub есть файлы в основном на языке разметки reStructuredText и т. д. Отсутствие управления версиями и отслеживанием приводит к публикации избыточной информации в нескольких источниках. В маркировке/категоризации информации нет единообразия. Поэтому при поиске необходим предыдущий опыт и знания.

Учитывая множество форматов и источников, ожидается, что информацию придется реструктурировать и централизовать с помощью mkdocs. Чтобы лучше понять эти инструменты, я изучил и ознакомился с их использованием.

Вердикт: существующая документация неструктурирована и разбросана без соответствующих ссылок. Ему также не хватает централизации и единообразия в форматировании. Это приводит к тому, что пользователям приходится тратить дополнительные усилия на поиск. Такие пробелы также создают ненужное давление на администраторов/специалистов по сопровождению/руководителей, из-за чего становится сложно поддерживать общественный подход к сопровождению и обновлению документации. Опыт пользователей и участников значительно ухудшился, и такие ситуации будут повторяться.

Структура предлагаемой документации. После тщательного анализа требований я решил устранить основные болевые точки с помощью реструктурированной модели документации.
Реструктурированная модель продемонстрирована на макете, прикрепленном ниже, и каждая часть документации будет разбита на следующие 7 категорий:

  • О
  • Начиная
  • Концепции
  • Интерфейсы Ручио
  • Задачи
  • Учебники
  • Передовые ноу-хау

Конечно, есть улучшения, такие как добавление ссылок, над которыми я хотел бы поработать после завершения этой программы. Учитывая, что более 1000 активных пользователей имеют доступ к 500 петабайтам данных на Rucio, предлагаемая реструктуризация его документации должна позволить значительно снизить потребность пользователей прибегать к списку рассылки поддержки. Целью будет улучшение пользовательского опыта за счет снижения количества кликов и упрощения доступа к документации посредством категоризации и маркировки. Все, что нужно знать с точки зрения пользователя/оператора/администратора, будет доступно в течение трех кликов или меньше.

Ссылка на макет: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Цели проекта: - Анализировать и отсекать избыточную информацию, доступную из различных источников. т.е. каждая часть информации должна иметь один источник истины. - Реструктуризация путем маркировки и категоризации существующей документации на различные части. - Перенос реструктурированной документации в централизованное представление на основе mkdocs. - Переформатирование/импорт документации, которую невозможно перенести из-за ограничений формата файла. пробелы заполняются – с точки зрения связей, обновления информации или исправления ошибок.

Базовые элементы этой системы уже созданы, однако моя модель могла бы улучшить существующую систему, установив надлежащие рекомендации по вкладу и управлению с соответствующей документацией. Кроме того, я планирую включить доски проектов GitHub для отслеживания проблем и общего состояния проекта.

Сроки: - До 16 августа --> Ознакомиться с текущими версиями документации и Ручио --> Изучить новые методы и навыки технического письма, которые будут полезны в течение срока проекта --> Содействовать решению проблем с документацией, если таковые имеются, о которых сообщается на GitHub

  • Сплочение сообщества (17 августа – 13 сентября) --> Настройте канал связи и время для учета разницы в часовых поясах (в Пуне на 3 часа 30 минут впереди) --> Основные болевые точки, которые необходимо определить для уточнения целей - -> Узнайте больше о сообществе, организации и структуре, участвуя в обсуждениях. --> Оценка предлагаемой структуры документации с наставниками и другими ключевыми членами организации на предмет жизнеспособности и осуществимости реализации. --> Доработка предлагаемых функций и любые другие изменения, которые могут потребоваться в существующей документации.

  • Период документации (14 сентября – 30 ноября) Основываясь на предлагаемом формате, который я сформулировал здесь, я предоставил разбивку основных этапов, которых я планирую достичь в течение периода документации.

--> Этап №1: Категоризация и маркировка ETC: 28 сентября 2020 г. Усвоение доступной документации и ее маркировка значительно упростят процесс реструктуризации и сокращения.

--> Этап № 2: анализ, сокращение и реструктуризация и т. д.: 19 октября 2020 г. Документация, которая была классифицирована на этапе № 1, будет проанализирована на наличие дубликатов и избыточных источников информации. Как указано в информации о проекте, мы стремимся к одному источнику правды для всей доступной информации.

--> Этап №3: Централизация и переформатирование: ETC: 9 ноября 2020 г. После того, как документация будет сокращена и реструктурирована должным образом, я бы хотел сначала ее переформатировать. Из-за различных источников форматы различаются, и их сначала необходимо преобразовать в соответствующий формат. Как только это будет сделано, процесс централизации станет проще.

--> Этап № 4: Создание досок отслеживания + документация по управлению/вкладам и т. д.: 23 ноября 2020 г. Этот этап призван гарантировать, что после завершения проекта документация будет оставаться обновленной. Установление руководящих принципов и создание советов по проектам облегчит бремя для административных членов по сбору вкладов сообщества и их эффективному отслеживанию.

--> Оценка проекта (30 ноября – 5 декабря) Отправить отчет о проекте и оценку моих наставников. Написать и представить отчет о моем опыте участия в Season of Docs.

Почему этот проект? Я считал, что дополнение кода хорошо написанной и версионной документацией — единственный способ обеспечить дальнейшее внедрение и лучшее использование. Лично я был очарован тем, как ЦЕРН стал пионером передовых исследований в различных областях физики. Учитывая масштабы информации, обрабатываемой, передаваемой и генерируемой в ходе таких экспериментов, меня всегда заинтриговало то, как данные управляются для справки и будущего использования внутри организации. Для меня было бы честью внести свой вклад в улучшение документации для платформы, которая послужила основой для некоторых удивительных научных исследований и открытий.

Почему я подходящий человек для этого проекта? Помимо выполнения предварительных условий, я уверен, что буду подходящим человеком для этого проекта, поскольку:

Я уже работаю над изменением существующей документации для Kubernetes. Благодаря этому вкладу меня зачислили в качестве тени документации по выпуску для цикла выпуска 1.19 Kubernetes, где я вношу свой вклад в эффективное сопровождение и обновление документации для новых функций, которые добавляются во время выпусков. Я считаю, что хорошая документация — это основа отличного продукта/услуги. Будь то процедурная или техническая информация, хорошо написанная, краткая и легкодоступная, она станет стимулом для внедрения и лучшего использования. На протяжении всей моей карьеры я работал с распределенными системами, управляемыми данными, и считаю, что лучше всех разбираюсь в тонкостях требований к документации для таких систем. Будучи конечным пользователем, я знаком с подводными камнями плохо написанной/неправильной документации и буду стараться учесть их во время реструктуризации.