На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- СимПи
- Технический писатель:
- Суми7
- Название проекта:
- Согласованность строк документации — документация Sympy
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Абстрактный :
Текущее состояние документации Sympy и предыдущая работа:
Работа по созданию официального руководства по стилю для SymPy завершена.
Проект GSoD Лорен Глаттли создал руководство по стилю для строк документации SymPy, которое можно найти в Руководстве по стилю документации SymPy.
Строки документации в специальном подмодуле и файлеsolvers.py были отредактированы, чтобы последовательно соответствовать рекомендациям нового руководства по стилю.
Все остальные строки документации в кодовой базе также предстояло отредактировать, чтобы они соответствовали новому руководству по стилю.
Предлагаемая работа:
Большинство строк документации в SymPy по-прежнему не соответствуют последнему руководству по стилю. Целью этого проекта будет обновление строк документации в SymPy, чтобы они соответствовали этому руководству.
Я обсуждал проект с наставниками. Вот ссылка на обсуждение.
Было решено, что редактирование строк документации по всей кодовой базе Sympy в соответствии с последним руководством по стилю — большая задача, и проект следует ограничиться ею.
Моя работа над проектом будет включать в себя внедрение нового руководства по обновлению существующих строк документации, а также сбор и устранение других несоответствий, таких как использование языка или терминов.
Порядок существующих подразделов можно изменить или решить позже или как отдельную задачу.
Демонстрация различий в результатах, когда параметрам передаются разные значения, путем добавления дополнительных примеров и добавления раздела параметров.
Продолжайте добавлять сложные примеры в раздел «Ошибки и подводные камни».
Вклад: - #17887: Работа над проблемой #17887: Добавление недостающих разделов документации в специальный подмодуль. Я добавил недостающий раздел «Параметры и примеры» в некоторые функции подмодуля «Специальные», который был отредактирован Л. Глаттли, чтобы следовать последнему руководству по стилю и служить моделью для будущих строк документации.
Вот ссылка на мой объединенный PR: https://github.com/sympy/sympy/pull/19334.
- #19591: выпуск #19591 соответствует руководству по стилю документации. Я добавил запрос на редактирование строки документации core.sympify в соответствии с последней версией руководства по стилю. Я добавил структурированные объяснения и примеры использования различных параметров.
Вот ссылка на PR: https://github.com/sympy/sympy/pull/19613
Цели проекта
Хронология до 17 августа:
- Продолжайте вносить вклад в организацию.
- Познакомьтесь поближе с пользовательской документацией и текущей версией Sympy.
- Изучите методы и навыки, которые будут полезны при реализации проекта.
Сплочение сообщества: (17 августа – 13 сентября 2020 г.)
- Настройте канал связи и время (из-за разницы во времени).
- Уточнить свои цели и установить ожидания обеих сторон.
- Обсуждаем порядок обновления модулей.
- Завершите порядок редактирования модулей, чтобы они соответствовали последнему руководству по стилю строки документации.
Период документации (14 сентября 2020 г. – 30 ноября 2020 г.):
Установите цели для достижения каждую неделю, желательно полное обновление документации одного модуля или подмодуля в неделю или чаще.
Для всех этих модулей моей основной целью будет добавление недостающих разделов и реструктуризация строк документации в соответствии с последним руководством по стилю. Это будет включать демонстрацию различных результатов, полученных при передаче разных значений параметрам. Все сложные выходы должны быть добавлены в раздел «Подводные камни и подводные камни».
Неделя 1 (14 – 21 сентября): Основная часть
Неделя 2 (22 сентября – 29 сентября): Функции: Комбинаторные подмодули
Неделя 3 (30 сентября – 6 октября): Функции
Неделя 4 (7–14 октября): Simplify, Crypto
Неделя 5 (15–21 октября): Диофантин.
Неделя 6 (22–29 октября): Холономика: субмодуль «Операции».
Неделя 7 (30 октября – 7 ноября): Модуль «Интегралы» (integrals.integrals), Вычисление интегралов с использованием G-функций Мейера.
Неделя 8 (8–15 ноября): физика, функции в конце модуля «Категории», модуль «Генерация кода», специальный подмодуль.
Неделя 9 (16–23 ноября): физика, функции в конце модуля «Категории», модуль «Генерация кода», специальный подмодуль.
Неделя 10 (24–30 ноября): раздел «Ошибки и подводные камни»
30 ноября – 5 декабря 2020 г., 18:00 UTC: Представление окончательного проекта и написание отчета.
3 - 10 декабря 2020 в 18:00 UTC: Представление успехов проекта и опыта работы с менторами
Порядок упомянутых здесь модулей может быть изменен после дальнейшего обсуждения с наставниками.
По предложению наставников, я сосредоточусь сначала на обновлении тех модулей, которые легче обновлять, затем перейду к сложным.
Почему я подходящий человек для этого проекта?
Я считаю себя подходящим человеком для этого проекта, поскольку у меня есть опыт написания технических статей в области компьютерных наук и я хорошо разбираюсь в git и github.
Поскольку я отправил запросы на обновление документации до последней версии руководства по стилю в Sympy, которые были успешно объединены, я уверен в рабочем процессе и регулярно вношу свой вклад.
Изначально, когда я начал писать, я столкнулся с некоторыми ошибками. Я наконец-то привык запускать тесты и создавать документацию каждый раз перед внесением изменений, поскольку это очень важно.
Мне очень комфортно участвовать в этом проекте, и я с нетерпением жду его.