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