На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- ЦЕРН-HSF
- Технический писатель:
- СабитаР
- Название проекта:
- Реструктуризация и оптимизация документации Allpix Squared
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
ОБЗОР Я выбрал проект Allpix Squared CERN-HSF по двум основным причинам:
Развитие навыков: существующая документация этого проекта является всеобъемлющей и объединяет несколько форматов контента. Аудит и реструктуризация этого обширного пакета документов помогут мне отточить мою информационную архитектуру и навыки письма. Кроме того, предметная область проекта (физика элементарных частиц!) для меня нова. Это заставляет меня оттачивать свои навыки взаимодействия с разработчиками. Я считаю, что технические писатели могут обрабатывать предложения разработчиков и представлять полезный контент для пользователей любого уровня, ЕСЛИ мы проведем необходимое предварительное исследование и зададим правильные вопросы. Этот проект позволит мне проверить эту теорию!
Технические ноу-хау: для этого проекта требуется Hugo — инструмент, который находится в верхней части моего списка для изучения. Я с нетерпением жду возможности изучить рабочий процесс LaTeX-Markdown-Hugo-GitLab-CI.
На этапе исследования технического писателя я кратко пообщался с наставниками проекта и ознакомился с существующей структурой пакета документации. Я также создал демонстрационный веб-сайт (https://ap2-demo.netlify.app/), чтобы проверить, смогу ли я правильно настроить Hugo и Docsy на своем компьютере с Windows. Мне удалось развернуть веб-сайт в Netlify, но не в Gitlab Pages. Чтобы этот проект сохранил текущий рабочий процесс развертывания, я найду способ развернуть тему Hugo Docsy на Gitlab Pages.
ОЖИДАЕМЫЕ РЕЗУЛЬТАТЫ ПРОЕКТА — оптимизированный веб-сайт проекта, объединяющий документацию, ссылки на код, учебные пособия и новости. - Реструктурированное и переработанное руководство пользователя, в котором разделяется контент, предназначенный для пользователей и разработчиков, и включается ранее отсутствующая информация. - Рабочий процесс учебных пособий на основе доступных примеров практической документации, часто задаваемых вопросов и часто встречающихся проблем.
ИНСТРУМЕНТЫ ПРОЕКТА В текущей документации Allpix Squared помимо GitLab и Gitlab CI используются LaTeX, Doxygen, pandoc и Hugo. Мы с наставниками проекта обсуждали возможность переноса контента из LaTeX в Markdown с помощью плагинов MathJax. Если мне это удастся, в рабочий процесс документации будут включены Hugo, Markdown, Doxygen, git и Gitlab CI. Чтобы хранить учебные пособия на одном веб-сайте/платформе, я буду использовать Hugo и Markdown. Мне интересно узнать о возможности использования Codelabs-as-a-Tool (ClaaT) для учебных пособий. В июле этого года я надеюсь протестировать рабочий процесс ClaaT-Hugo и обсудить его с наставниками, если они будут выбраны.
ПРОДОЛЖИТЕЛЬНОСТЬ ПРОЕКТА Я прошу завершить проект Allpix Squared в течение стандартного трехмесячного периода (14 сентября 2020 г. – 30 ноября 2020 г.), в течение которого я потрачу ок. 15 часов в неделю на это. Эти часы будут включать встречи с наставниками и соответствующие электронные письма, если это необходимо. Я также буду придерживаться сроков GSoD для взаимодействия с сообществом и завершения проекта.
ЗАДАЧИ ПРОЕКТА Вот как я намерен реализовать предлагаемые мной обновления существующего пакета документации Allpix Squared: 1. Исследование, обсуждение и изучение вариантов (17 августа – 13 сентября 2020 г.): - Понять требования проекта - Установить программное обеспечение Allpix Squared для идентификации недостающая информация, если таковая имеется, в текущих документах. - Запросите необходимые учетные данные. - Создавайте рабочие процессы для разных пользователей Allpix Squared. - Классифицируйте контент по роли пользователя. - Проверьте последствия преобразования файлов LaTeX в Markdown. - Объедините исходные репозитории или узнайте, как работать с несколькими репозиториями git. - Бонус: протестируйте CLaaT как вариант для учебных пособий. - Бонус: напишите краткое руководство по стилю/справочник по коротким кодам, чтобы помочь участникам поддерживать документацию. Хронология: этап объединения сообщества.
Реструктуризация, просмотр и улучшение контента (14 сентября — 19 октября 2020 г.): два задания в неделю, примерно 5–7 часов на каждое. Этот график включает буферную неделю для устранения непредвиденных задержек или проблем.
- Просмотрите существующий контент и классификации пользователей с учетом рабочих процессов пользователей.
- Опишите и протестируйте рабочий процесс реструктурированного контента для разных пользователей.
- Найдите и дополните недостающий контент
- Конвертируйте файлы LaTeX в Markdown
- Завершить подготовку руководства пользователя и содержания руководства разработчика.
- Создание PDF-файлов с руководствами пользователя и разработчика.
- Бонус: Структурируйте содержание руководств на основе примеров и задач.
- Бонус: настройка учебного процесса для практических примеров. Сроки: 5 недель (этап разработки документа).
Создание веб-сайта (19 октября — 30 ноября 2020 г.): 1–2 задания в неделю, примерно 5–7 часов на каждое. Этот график включает в себя буферную неделю для устранения проблем и точной настройки конечного результата.
- Понимание и тестирование рабочего процесса публикации
- Создайте структуру веб-сайта с помощью Hugo и Docsy.
- Проверьте, как поддерживать текущее автоматическое развертывание и рабочий процесс с помощью Docsy.
- Извлекайте контент из Doxygen
- Разработайте руководство пользователя, руководство для разработчиков и учебные пособия на основе контента LaTex или Markdown.
- Завершить внешний вид веб-сайта проекта (логотип, цвета, шаблон, макет, ссылки, удобство использования и Gitlab CI/CD). Срок: 6 недель (этап разработки документа).