Как внести вклад в документацию NumPy

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

Если вы читаете эту страницу, вы, вероятно, хотите помочь. Это руководство поможет вам определить, какой тип контента вы будете писать, а также даст вам некоторые советы и инструкции по его отправке в официальную документацию NumPy (то есть документацию, поставляемую с NumPy и размещённую на официальных страницах проекта). Имейте в виду, что если вы не хотите этого делать, написание учебного пособия на своём блоге, создание видео на YouTube или ответы на вопросы в социальных сетях или на Stack Overflow также являются отличными вкладами!

В NumPy есть команда по документации. Мы проводим открытые встречи в Zoom каждые три недели и приглашаем всех присоединиться. Не стесняйтесь обращаться к нам, если у вас есть вопросы или вам просто нужна помощь в выполнении первых шагов — мы всегда рады помочь. Обычно о встречах объявляется на рассылке numpy-discussion. Протоколы встреч ведётся на hackmd.io и хранятся в репозитории NumPy Archive.

Вы можете найти более масштабные запланированные и выполняемые идеи по улучшению документации на странице проекта GitHub.

Текущее видение документации: NEP 44

Недавно сообщество NumPy одобрило предложение по улучшению NumPy (NEP) по документации, NEP 44 — Реструктуризация документации NumPy.

Где находится документация?

Главная страница документации NumPy перечисляет несколько категорий. Упомянутые там документы находятся в разных местах.

• Учебные пособия, пошаговые руководства, объяснения: Эти документы хранятся в дереве исходного кода NumPy, а это значит, что для добавления их в официальную документацию необходимо загрузить исходный код NumPy, сгенерировать его и отправить свои изменения через запрос на добавление в GitHub.
• Справочник API: Они в основном являются результатом рендеринга документации кода NumPy в отформатированные документы. Они автоматически генерируются при создании документации из исходного кода.

Наборы данных

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

Примечание: в настоящее время мы не можем легко использовать данные из других пакетов (кроме, например, из SciPy или Matplotlib). Мы планируем создать отдельный пакет наборов данных, но он пока не готов — пожалуйста, обсудите с нами, если у вас есть идеи по источникам данных.

Создание нового контента

Документация написана в формате restructuredText, который является форматом, используемым Sphinx, инструментом, который большинство проектов Python используют для автоматической генерации и связывания документации в рамках проекта. Вы можете ознакомиться с кратким руководством по restructuredText или начальным руководством по restructuredText для получения дополнительной информации.

Если вы уже определили, какой тип документа вы хотите написать, вы можете ознакомиться со следующими конкретными руководствами:

• Руководство по написанию учебных пособий (TODO)
• Руководство по написанию справочной (API) документации: руководство по docstring numpydoc

Основные дополнения к документации (например, новые учебные пособия) должны быть предложены на рассылки.

Другие способы внесения вклада

Исправление технических неточностей в документации имеет высокий приоритет. Например, если в docstring отсутствует параметр или описание функции/параметра/метода и т. д. неверно. Другие «структурные» дефекты, такие как неработающие ссылки, также имеют высокий приоритет.

Предложения по изменениям, которые улучшают ясность документации, приветствуются. Однако «ясность» является несколько субъективной, поэтому такие предложения лучше всего делать, поднимая вопросы, описывающие, что можно улучшить в текущей документации. Предложения, которые включают конкретные предложения по улучшению, поощряются, так как предлагаемые изменения помогают сформулировать обсуждение.

Основываясь на вышеизложенном описании, изменения «высокого приоритета» (например, исправление технических неточностей, неработающих ссылок и т. д.) могут быть предложены непосредственно через запросы на добавление, так как их легко проверить. Другие изменения должны быть сначала подняты в виде вопросов, чтобы обсуждение могло состояться перед внесением крупных изменений, что, в принципе, поможет вам избежать траты времени на нежелательные изменения.

Если вы видите хорошее учебное пособие, пошаговое руководство или объяснение, которое не включено в официальную документацию, вы можете предложить его добавление, создав вопрос на GitHub. Аналогично, создание вопросов для предложения учебного пособия, пошагового руководства или объяснения, которое вы не можете найти, является отличным способом помочь команде по документации направить усилия на то, что пользователи ищут. Посмотрите этот вопрос для примера того, как это сделать.

Наконец, если вы обнаружите опечатку или ошибку в документации или хотите предложить другой подход, вы также можете создать вопрос или отправить запрос на добавление с вашим предложением. Имейте в виду, что изменения, исправляюшие грамматические/орфографические ошибки, приветствуются, но не обязательно имеют самый высокий приоритет. «Грамматическая правильность» часто путается со «стилем», что может привести к бесплодным обсуждениям, которые не обязательно улучшат что-либо. Изменения, которые изменяют формулировки или переставляют фразы без изменения технического содержания, не рекомендуются. Если вы считаете, что другая формулировка улучшает ясность, вы должны создать вопрос, как указано выше, но снова изменения такого рода очень часто носят субъективный характер и не обязательно улучшают качество документации.

Дополнительные советы

• Не беспокойтесь, если английский язык не является вашим родным. Постарайтесь сделать всё возможное — мы пересмотрим ваш контент и убедимся, что мы исправили любые проблемы с кодом или текстом.
• Если вы не уверены, полезно ли ваше учебное пособие для сообщества, рассмотрите возможность создания вопроса на GitHub, предложив его, или задайте вопрос на рассылке или Stack Overflow.
• Если вы не знакомы с git/GitHub или процессом отправки запроса на добавление (PR), ознакомьтесь с нашим руководством по участию.

Другие интересные материалы

• writethedocs.org содержит множество интересных ресурсов по технической документации.
• Google предлагает два бесплатных курса по технической документации
• Software Carpentry содержит множество хороших рекомендаций для создания образовательных материалов.