проект ДИПИ

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

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

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

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

Я инженер-программист и имею опыт написания технических статей. Имею более 4 лет опыта в написании высококачественной документации по программному обеспечению, руководств пользователя, руководств, описаний проектов. Я живу в Исламабаде, Пакистан (часовой пояс: UTC + 5). В настоящее время я работаю стажером в Outreachy, который продлится до 18 августа. Я участвовал в Google Season of Docs в качестве технического писателя в организации OpenELIS Global. Исходная документация была на французском языке, ограничена и устарела, поэтому я создал обширную и обновленную документацию для конечных пользователей на английском языке. Меня выбрали в Outreachy в организацию Perl & Raku на май-август 2020 года в качестве бэкенд-разработчика сервера Open Food Facts. Помимо back-end разработки, одной из основных задач этой стажировки является создание документации для модулей и функций в формате POD. Я вошел в мир открытого исходного кода в прошлом году, когда участвовал в нескольких проектах с открытым исходным кодом, а затем принял участие в Google Season of Docs. А в этом году меня выбрали в Outreachy, которая поддерживает разнообразие открытого и бесплатного программного обеспечения. Я хорошо владею Git, поскольку мой проект Outreachy размещен на GitHub, и с марта я регулярно делаю материалы для Open Food Facts и Mozilla Fenix. Я являюсь пользователем Linux более 3 лет и с тех пор использую команды терминала.

Инструменты и языки документации, которые я использовал, — это Sphinx, Read the docs, Markdown. Мне понравилась эта идея, и я хочу поработать над ней, потому что у меня есть соответствующий опыт, и я хотел бы использовать свои знания и навыки, чтобы внести свой вклад в DIPY. Имею опыт работы в сфере цифровой обработки изображений, компьютерного зрения, машинного обучения. Это поможет мне лучше понять нейровизуализацию и помочь в создании документации. Имею огромный опыт работы в медицинской сфере. Я разработал медицинский сайт для врачей, пациентов, лабораторий, водителей скорой помощи. Я работал над другой системой, которую используют врачи, пациенты, медсестры, лаборанты и исследователи. Это поможет мне в создании документации, которую будет легче понять аудитории.

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

Я планирую сделать следующее:

Определить конкретную структуру и шаблон для документации. Изменить документацию таким образом, чтобы пользователи могли легко перемещаться и находить необходимую информацию. Создать дорожную карту или список рабочих элементов для вовлечения сообщества в дальнейшую работу с документацией. Определить шаблоны для руководства пользователя и руководства разработчика. Определить. шаблоны для руководства по содействию. Перепишите, реструктурируйте и обновите руководство пользователя, руководство по разработке и руководство по содействию (которые могут помочь и мотивировать новых пользователей внести свой вклад в проект). Добавьте нетекстовые изображения для улучшения текстовых объяснений. Улучшите согласованность документации. Создайте документацию для новый интерфейс командной строки

Гид пользователя:

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

Руководство разработчика:

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

ШАБЛОН

Это один из шаблонов, которые можно использовать для руководства по участию. Его можно изменить, а разделы можно добавить или удалить в соответствии с требованиями документа.

Вклад в DIPY

  • Приветственное примечание

ТОС

Нормы поведения

  • Наши стандарты
  • Примеры поведения, способствующего созданию позитивной обстановки
  • Примеры неприемлемого поведения участников
  • Наши обязанности
  • Обязанности сопровождающих проекта
  • Объем

Область применения Кодекса поведения

Что мне нужно знать, чтобы помочь?

Если вы хотите помочь с написанием кода, наш проект использует [вставьте список языков программирования, фреймворков или инструментов, которые использует ваш проект]. Если вы еще не готовы внести свой вклад в код, не проблема! Вы также можете проверить проблемы с документацией [ссылка на метку или тег документации в вашем трекере проблем] или проблемы с дизайном, которые у нас есть [ссылка на метку дизайна или тег в трекере проблем, если ваш проект отслеживает проблемы с дизайном]. Если вы заинтересованы в том, чтобы внести свой вклад в код и хотели бы узнать больше о технологиях, которые мы используем, ознакомьтесь со списком ниже. Включите маркированный список ресурсов (руководства, видео, книги), которые новые участники могут использовать, чтобы узнать, что пользователям необходимо знать, чтобы внести свой вклад в проект.

Настройка среды разработки

В этом разделе я добавлю процедуру установки и зависимости, которые необходимо установить. Установите $project, выполнив: install project

  • Исходный код: github.com/$project/$project.
  • Отслеживание проблем: github.com/$project/$project/issues.

Как внести свой вклад

Как сообщить об ошибке

  • Прежде чем отправлять отчет об ошибке
  • Как мне отправить (хороший) отчет об ошибке?

Как отправить изменения

  • Протоколы запросов на включение
  • Ответ от команды
  • Скорость ответа

Как запросить улучшение

  • Прежде чем отправлять предложение по улучшению
  • Как мне подать (хорошее) предложение по улучшению?

Ваш первый вклад в код

  • Проблемы для начинающих
  • Помощь в решении проблем #### Pull Request
  • Процесс создания запроса на включение
  • Убедитесь, что все проверки состояния проходят.

Что делать, если проверки статуса не пройдены?

  • Написание тестов
  • Тестовое покрытие

Руководства по стилю

  • Сообщения о коммитах Git
  • Стандартный стиль

Поддерживать

Если у вас возникли проблемы, пожалуйста, сообщите нам об этом. Если вам нужна помощь, вы можете задать вопросы в нашем списке рассылки по адресу: project@google-groups.com, в чате IRC или [перечислите любые другие коммуникационные платформы, которые использует ваш проект].

Лицензия

В этом разделе будет рассказано о лицензии проекта.

Время и общение:

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