Эта страница переведена с помощью Cloud Translation API.

глобальный проект Моха

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

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

Организация с открытым исходным кодом:: моя глобальная
Технический писатель:: Тлазипанда
Название проекта:: Документация технического руководства по внедрению FLINT
Длина проекта:: Стандартная продолжительность (3 месяца)

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

Документация руководства по техническому внедрению для FLINT, помогающая новым участникам пройти техническую адаптацию, чтобы новые участники могли легко приступить к работе с минимальной поддержкой со стороны сопровождающих.

Проблемы проекта

Ниже приводится список наиболее важных проблем, связанных с текущей документацией: - Неорганизованные части инструкций по локальной установке, что затрудняет начало работы для новых участников. - В нескольких репозиториях FLINT отсутствует документация об их назначении, и они не связаны друг с другом, что затрудняет новичку определение того, какой репозиторий следует установить. - Установка Windows хорошо документирована, но документацию по установке для Linux можно улучшить. — Рабочий процесс Git в настоящее время не является частью документации.

Предложенное решение

В этом предложении представлено решение, позволяющее новым участникам пройти техническую адаптацию, чтобы новые участники могли легко приступить к работе с минимальной поддержкой со стороны сопровождающих. Этого можно достичь путем рефакторинга текущей документации, чтобы сделать ее удобной для новичков, а также путем создания центрального автономного репозитория для всей доступной документации. Проект разделен на три этапа: - Обзор существующей документации и рефакторинг. Целью этого этапа является рассмотрение текущего руководства и его рефакторинг таким образом, чтобы сделать его кратким и понятным для новых участников. Документацию также необходимо изменить, чтобы сделать ее более удобной для новичков, добавив значки, смайлы и информацию о проблемах, помеченных тегами «только для новичков» или «хорошие теги для первой проблемы». - Создайте центральный автономный репозиторий документации. Цель этого этапа — связать всю доступную документацию в логическом последовательном порядке в автономном репозитории. Это включает в себя заказ руководств по участию, инструкций по настройке проекта и пошаговых руководств. - Добавьте рабочий процесс разработчика и веб-сайт сообщества для новых разработчиков. Цель этого этапа — добавить рабочий процесс разработчика, который содержит рекомендации по вкладу git и техническую архитектуру проекта, а также рекомендации по тестированию и обеспечению качества. Предлагаемый веб-сайт сообщества будет представлять собой одностраничное приложение, отображающее рабочий процесс, проблемы, с которыми сталкиваются впервые, и список всех участников. Этап 1. Обзор существующей документации и рефакторинг:

Измените текущую документацию следующих репозиториев: - FLINT: текущая документация не очень подробная и не обеспечивает последовательный порядок необходимых обязательных библиотек. Пошаговые инструкции разделены на разные PDF-файлы, но их можно объединить в одном месте в более сжатой форме. Кроме того, руководства по установке предназначены для Windows, но для установки Linux может оказаться полезным перенаправление в репозиторий FLINT.docker. - FLINT.docker: в текущей документации не указана цель настройки этого репозитория, а именно обеспечение установки FLINT в Linux через Docker. Поддержка через Docker ограничена только Ubuntu 18.04 (Bionic Beaver), но может быть распространена на другие дистрибутивы на базе Linux. В текущей документации также необходимо сделать акцент на последовательной настройке файлов Docker, а также на достаточном количестве информации о том, как выполнять сборку из файла makefile. - FLINT.example: в текущей документации не указана цель создания этого репозитория, а именно предоставление примера использования FLINT. Различные прогоны проб можно лучше разделить с помощью конкретных инструкций по их запуску. Нам также необходимо связать этот репозиторий с нашим основным репозиторием FLINT, чтобы пользователи могли перемещаться по нему и проверить пример в действии.

В текущую документацию необходимо добавить следующую информацию: - Использование Git и GitHub: сюда будут включены пошаговые инструкции о том, как разветвить, клонировать, а затем настроить удаленный восходящий поток для репозитория. Он также предоставит информацию о том, как выполнять перебазирование с использованием последней главной версии и обрабатывать конфликты слияния. - Значки и смайлы: в текущей документации отсутствуют значки и смайлы, которые могут помочь новым участникам почувствовать себя желанными гостями и решить проблемы менее пугающими. - Информация о вопросах, ориентированных на новичков/новичков: это поможет перенаправить новых участников на вопросы, ориентированные на новичков, и на веб-сайт сообщества. - Информация о репозитории Import-me: Репозиторий Import-me действует как базовый шаблон для запуска любого глобального репозитория Moja. В текущей документации не упоминается важность этого. Его необходимо обновить, указав репозиторий Import-me, а также необходимо добавить шаги по выбору его в качестве шаблона при создании нового репозитория. Также должен быть установлен порядок, позволяющий программистам предлагать дополнительные функции для репозитория Import-me.

Этап 2. Создайте центральный автономный репозиторий документации:

Инструмент, который будет использоваться для хостинговой платформы:

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

Организуйте весь контент в логической последовательной манере:

Предлагаемый порядок содержания следующий: - - Введение в документацию для разработчиков: в этом разделе описывается введение в Moja Global и FLINT. - Вклад: этот раздел будет состоять из подразделов «Способы внесения вклада» (с точки зрения кода/сообщения об ошибках/перевода/документации/организации мероприятий и т. д.) и «Кодекса поведения». - Настройка разработки: этот раздел будет состоять из подразделов «Рабочий процесс Git и GitHub», «Установка Windows», «Установка Linux». - Рабочий процесс разработчика: этот раздел будет состоять из обсуждения инструментов, интегрированных для тестирования, а также способов выполнения ручного тестирования вашего запроса на включение и многое другое, как описано на следующем этапе. - Присоединяйтесь к нам: в этом разделе будут представлены различные социальные форумы, такие как каналы Slack, для связи и работы с Moja Global.

Этап 3. Добавьте рабочий процесс разработчика и веб-сайт сообщества для новых участников:

Документация рабочего процесса разработчика:

Документация по рабочему процессу разработчика будет состоять из следующих подразделов:

Используемый технологический стек/архитектура и различные модули в коде: документация для ознакомления новых участников с реализованным техническим стеком, различными библиотеками и модулями кодовой базы.
Интегрированные инструменты тестирования и покрытия: новые участники знакомятся с инструментами конвейера CI/CD, используемыми для тестирования, ботами покрытия и автоматическими проверками качества, выполняемыми на основе их кода. Также предоставив им рекомендации о том, к кому обращаться, если тесты не пройдут.
Боты, используемые для упрощения рабочего процесса, например — Zulipbot: разработка шаблонов контента для отображения ботов и доступности документации, чтобы пользователи могли понимать ботов и даже улучшать конфигурацию ботов, внося свой вклад.
Ручное тестирование и отправка запроса на включение: необходимо предоставить документацию о том, как вручную проверять запросы на включение на соответствие определенным стандартам и загружать результаты в виде снимков экрана/гифок при отправке запросов на включение.
Рекомендации по проверке запросов на включение, которым должны следовать участники: Рекомендации по пометке определенных команд для проверки и добавлению меток, таких как «требуется проверка», к запросу на включение, чтобы сопровождающие могли ответить в ответ.

Веб-сайт сообщества:

Веб-сайт сообщества будет иметь следующие функции:

Информация о нашем рабочем процессе: Рабочий процесс будет состоять из серии действий, с которых может начать новый участник, например, заявления о проблеме, возникшей впервые, с последующим созданием проблемы, возникающей впервые, для кого-то другого и помощи другим, предоставляя отзывы и просматривая их запросы на включение.
Список проблем, предназначенных только для новичков: список проблем, специально предназначенных для новичков или новых участников.
Список устаревших проблем: список проблем, над которыми не работали в течение длительного периода времени и, следовательно, которые доступны участникам для выбора.
Список участников: список участников, которые на данный момент внесли свой вклад в репозитории Moja Global.
Недавние участники: список участников, которые недавно внесли свой вклад в репозитории Moja Global.
Ссылки для присоединения к чат-форумам: информация и ссылки для присоединения к сообществу Slack для решения вопросов и дальнейшего обсуждения проектов.