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

Проект NumPy

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

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

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

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

Введение

NumPy обеспечивает чистые и быстрые вычисления на основе массивов в бесплатной библиотеке программного обеспечения с открытым исходным кодом. Это фундаментальный пакет в стеке SciPy для научных вычислений [1]. Более 370 тысяч проектов используют для эффективных вычислений массивы [2]. Пользователей NumPy встречает новый сайт с приложениями и кейсами [1]. Когда новый пользователь находит страницу документации, он встречает множество ссылок «Начни здесь» и вводные руководства, которые могут оказаться непосильными для новичка, например, основы NumPy/обмен байтов. Я начал использовать NumPy десять лет назад, еще в аспирантуре. Я обнаружил, что собираю сообщения в блогах, конспекты лекций и ответы StackExchange, чтобы не просматривать документацию NumPy. В настоящее время существует более 360 тысяч разговоров StackExchange, посвященных NumPy. Я полагаю, что у других пользователей были аналогичные пути к успеху в NumPy. Строительными блоками образовательных инструментов являются общение и сообщество [4]. Документация должна создать сообщество, отражающее желаемые цели проекта. Документация должна быть последовательным и четким руководством для нового пользователя. Учебные пособия должны давать новым пользователям простые для понимания шаги и обеспечивать удобство работы с библиотекой [3]. Документация должна приветствовать нового пользователя в сообществе NumPy. Структура, темп и авторы документации — все это должно создать место, где приветствуется исследование и общение. Это предложение позволит систематизировать и заполнить пробелы в текущей документации NumPy, чтобы новые пользователи были обучены и приняты в сообщество.

Знания, которые передают пользователи, получаются путем тестирования и экспериментирования [4,5]. Знания зависят от метода тестирования и оценки. Контент, в котором представлены четкие цели и способы применения, позволяет пользователям тестировать и оценивать новые идеи и методы. Сообщество может создать базу знаний, улучшить навыки, факты и приложения. Пространство с практическими рекомендациями дает двойную выгоду. Во-первых, у новых и опытных пользователей есть набор четких целей для тестирования и проведения экспериментов. Во-вторых, потенциальные участники документации имеют возможность сообщить о своих целях, методах и решениях. Раздел с практическими рекомендациями отвечает насущной необходимости сделать документацию NumPy более доступной для новых пользователей и возможных участников. Текущие знания

Джон Дьюи говорил, что основой обучения является подлинный опыт [4]. Сообщество NumPy обладает огромным опытом, которым можно поделиться с другими пользователями. Образование построено на сообществе и общении. Организованная страница документации открывает новым пользователям возможность познакомиться с NumPy. Он также создает структурированный шаблон для потенциальных участников, которые могут поделиться своим опытом в NumPy.

Существует четыре широко сгруппированных пространства для документации по программному обеспечению [3]: пространство для учебных пособий, пространство для практических рекомендаций, пространство для объяснений и пространство для справок. Документация NumPy содержит ряд документов в учебном пространстве, в которых сочетаются объяснения и инструкции по размещению содержимого в учебном пособии. Учебное пространство должно быть сосредоточено на обучении пользователей и использовать легко повторяемые шаги для передачи идей. В разделе практических рекомендаций представлены более целенаправленные процедуры, которые пользователи могут применять в реальных приложениях. Пространство объяснений предоставляет подробную информацию и подробные строки документации по каждой функции. Текущее руководство и разделы с практическими рекомендациями четко не разграничены и иногда занимают пространство объяснений и справок. Существует отличное руководство для «абсолютных новичков», а для пользователей Matlab есть отличное руководство по созданию кода NumPy в «Numpy для пользователей Matlab». Четкое разграничение этих четырех пространств делает документацию более понятной.

Пробел в базе знаний/неудовлетворенные потребности

Текущая документация охватывает множество необходимых тем, но в ней отсутствует четкое различие между учебником, практическими рекомендациями, объяснениями и справочными разделами. Это приводит в замешательство потенциальных участников. Новые пользователи могут быть перегружены пояснениями и справочными материалами в разделе учебных пособий, а потенциальные участники сталкиваются с препятствиями при внесении своего вклада. Я предлагаю более доступный макет для новичков и возможных участников документации с логическим потоком документации и управлением запросами на включение новых участников в предоставленные пользователями практические документы. Моя долгосрочная цель — создать сообщество документации, чтобы изучение документации было взаимовыгодным опытом обучения и общения. Эта модель документации позволит основать обучение на реальном опыте для новичков и потенциальных участников.

Обоснование

Это предложение Google Summer of Docs важно для моих педагогических и карьерных целей. Я использую NumPy и SciPy во всех своих курсах. Моим ученикам сложно ориентироваться в текущей документации. Я хочу использовать свой опыт преподавания программирования тем, кто не знаком с CS, чтобы помочь в организации, редактировании и заполнении пробелов в текущих руководствах. Затем я смогу использовать документацию в качестве учебника и справочного материала для своих курсов. Я создал десятки руководств, упражнений и примеров, используя Python и . Я хочу преобразовать часть этого материала в учебные пособия и инструкции. У меня было более 800 студентов, использующих NumPy (как часть стека Scipy), и у меня есть несколько студентов, которые заинтересованы в том, чтобы стать участниками документации в осеннем семестре. Я преподаю в машиностроительном университете Коннектикута в течение 4 лет и прочитал более 30 кредитных часов курсов.

Конкретные цели

У меня есть три конкретные цели для этого предложения Google Summer of Docs: 1. Упорядочить текущую документацию, 2. Отредактировать текущие учебные пособия (Руководство для начинающих, Создание массива, Индексирование, Линейная алгебра и NumPy для Matlab), чтобы переместить справочную информацию в Объяснение. Пространство и 3. Вместе с учащимися подготовьте практические материалы. Каждая конкретная цель имеет ожидаемый результат для предложения.

Эти три конкретные цели призваны сделать документацию более привлекательной для новых пользователей и обеспечить структуру для потенциальных участников. Эти цели также помогают достижению долгосрочной цели — продолжения роста сообщества документации NumPy. Ожидаемые результаты

У меня есть три ожидаемых результата: 1. Переработанная веб-страница документации, которая четко разделяет четыре области: учебные пособия, инструкции, объяснения и ссылки. 2. Новые учебные пособия по: чтению и записи массивов, созданию массивов (np.zeros, np.ones, np.block и т. д.), а также операции поэлементной и линейной алгебры в NumPy и 3. тщательно подобранное пространство с практическими рекомендациями.

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

Новые участники документации могут предоставлять миллионам пользователей небольшие варианты использования без создания всей документации Sphinx. Мы хотим продолжать строить наше сообщество преподавания и обучения. Предлагаемая документация будет имитировать текущую документацию с открытым исходным кодом, такую как Matplotlib, Divio и т. д. Новым пользователям и потенциальным участникам будет легче научиться применять NumPy в своих областях и программном обеспечении.

Срок реализации проекта: 14.09-30.11. Первым шагом является объединение документации и отдельных материалов текущих руководств в учебные материалы, инструкции и пояснения. Это будет сделано в течение первых пяти недель проекта в рамках Результатов 1 и 2 — пересмотра веб-сайта и учебных пособий соответственно. Предлагаемая организация документации показана в предлагаемой документации ниже.

Предлагаемая документация:

i.Учебники:

Абсолютные основы для новичков (удалить установку, можно ли импорт/экспорт панд заменить на numpy.loadtxt?)
ссылка на «Что такое numpy»
ссылка на базовые инструкции по установке здесь
Краткое руководство (предназначено для продолжения руководства по Python)
Работа с массивами NumPy
создание массива (np.zeros, np.ones, np.block и т. д.) (запишите: med-низкий приоритет)
поэлементные операции (+,-,*,/) и операции линейной алгебры (+,-,@, linalg.solve) (приоритет записи:med)
Чтение и запись данных с помощью Numpy (запись: высокий приоритет)
Индексирование

ii. Практическое руководство:

Линейная алгебра на n-мерных массивах (хотелось бы отредактировать заголовки и описания и, возможно, изменить заголовок на «Обработка изображений с помощью линейной алгебры Numpy»)
ссылка на практический контент numpy-tutorials (текущая работа)

iii. Объяснение:

Типы данных
Ввод-вывод с помощью Numpy
Индексирование
Вещание
Обмен байтами
Структурированные массивы
Написание пользовательских контейнеров массивов
подкласс ndarray
Разнообразный

iv. Эталонное пространство:

Глоссарий
Справочник по API Numpy
Numpy для пользователей Matlab (таблица эквивалентности — отличная справочная таблица, но обсуждение массива/матрицы отвлекает и кажется устаревшим)

По завершении этого сезона документации Google я предлагаю следующие результаты:

Пересмотренная веб-страница документации, которая четко разделяет четыре раздела: учебные пособия, инструкции, пояснения и ссылки.
Новые учебные пособия по созданию массивов (np.zeros, np.ones, np.block и т. д.), поэлементным операциям (+,-,*,/) и операциям линейной алгебры (+,-,@, linalg.solve). ), а также чтение и запись данных с помощью Numpy (высокий приоритет).
Рекомендации по использованию документов для увеличения вклада пользователей и содействия достижению целей сообщества в преподавании и обучении.

Каждый результат состоит из ряда этапов, указанных ниже в таблицах для Результатов 1–3. Пока предлагаемая документация отправлена на рассмотрение, высокоприоритетное руководство «Чтение/запись массивов» будет написано для отправки в виде запроса на включение в рамках Результата 2. Во время проверки обновленного веб-сайта и обновленного руководства «Чтение/запись массивов» , я начну писать руководство по созданию массивов с использованием функций NumPy, например np.ones, np.zeros, np.diag. Оставшееся время будет использовано для реагирования на проблемы с запросами на включение и начала написания руководства 3-го ранга: Операции поэлементной и линейной алгебры в Python.

Третий результат — посоветовать студентам Университета Коннектикута создавать документацию в репозитории numpy-tutorials. Представленные учебные пособия или практические документы будут представлять собой блокноты Jupyter, в которых используется NumPy для решения инженерных задач. Я буду использовать некоторые из своих заметок/примеров курса, чтобы представить пример блокнота. Я посоветую студентам следить за макетом и структурой при создании шаблона и схемы каркаса. Этот результат дает учащимся подлинный опыт общения с концепциями и решениями более широкой аудитории. Это прекрасная возможность для студентов поучаствовать в сообществе NumPy и учиться.

Результат 1: Пересмотреть веб-сайт. Дата завершения. Репозиторий ветки и собрать документы с помощью Sphinx. 21.09. Создать веб-страницу с четырьмя определенными и связанными пространствами. 1.10.1 Переместить текущие руководства в соответствующие места и создать документацию. 10.10. Отправить PR на github с предлагаемыми изменениями. 1.11. Отвечать на комментарии/предложения и пересматривать PR, текущий результат 2. Веб-сайт пересмотрен 30 ноября.

Результат 2: Пересмотр учебных пособий. Дата завершения. Рейтинг ревизий учебных пособий по обзору. 9/21. Разделение текущего содержания учебного пособия на области учебников и пояснений. 10/1. Рейтинг записи 1: Чтение/запись массивов. 10/10. Отправка PR на github для разделения и доработки. 10/20. Написание ранг 2: Создание массива PR 11/15 Написание ранга 3: Операции поэлементной и линейной алгебры PR 11/30

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

Чтение/запись массивов, в настоящее время пустая страница
Создание массива (np.zeros, np.ones, np.block и т. д.) Не существует: поможет новым пользователям объяснить и продемонстрировать общие инструменты создания/взаимодействия массива.
Операции поэлементной и линейной алгебры (+,-,*,/ и +,-@,linalg.solve) Не существует: это особенно полезно для 1. пользователей Matlab и 2. людей, переходящих на линейную алгебру (машинное обучение, линейная регрессия и др.)

Результат 3: Кураторское пространство с практическими рекомендациями Дата поставки Внешняя ссылка (проблема/пример) Создание примера с практическими рекомендациями (кандидат: Как найти собственные частоты гитарных струн 10/20
Создание шаблона с практическими рекомендациями для новых участников. 10/1 в разработке. Шаблон учебного пособия. PR и формулирование возможных вкладов. Работа с другими участниками над созданием блокнотов с практическими рекомендациями по набору студентов Калифорнийского университета в Коннектикуте и других членов сообщества. Статус 7/1: работа-учеба одобрена, заявки поступают.

Ожидаемая значимость

Это предложение Google Summer of Docs позволит создать документацию NumPy, заполнить недостающие учебные пособия на веб-сайте и привлечь участников документации. Как профессор машиностроения, я планирую сегментировать документацию таким образом, чтобы мои студенты могли ориентироваться в документах и легко находить вводные руководства, а не практические руководства. Сегментированная документация: руководство, инструкции, ссылки и пояснения предоставят потенциальным участникам структурированные примеры для создания новых ресурсов. Предлагаемая документация предоставляет возможность обмена информацией посредством обучения и общения как для новых, так и для опытных пользователей. Предлагаемая инструкция по документированию консультаций со студентами Университета Коннектикута позволит реализовать эту идею обучения и коммуникации на практике. Мы хотим, чтобы все пользователи могли экспериментировать, учиться и присоединяться к сообществу NumPy.