На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Матплотлиб
- Технический писатель:
- Джеромев
- Название проекта:
- Разработка путей входа в Matplotlib
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
Введение
Проектное предложение Matplotlib для Google Season of Docs в этом году предполагает создание контента, который поможет представить Matplotlib новым пользователям. Для разработки путей входа в Matplotlib я предлагаю подход, альтернативный подходу, используемому в текущей документации. Я новый технический писатель в отрасли; однако мой опыт работы связан с образованием и смежными с ним областями. Техническое письмо и образование имеют сильные параллели, которые направлены на создание контента, который вызывает сочувствие и позволяет пользователям выполнять свои задачи с помощью предоставленных ресурсов.
В этом контексте документация Matplotlib выиграет от улучшения сопереживания новым пользователям. Большая часть материала на данный момент состоит из рандомизированных данных и неразмеченных визуальных эффектов. Они отлично подходят для быстрого отображения визуальных эффектов и функций Matplotlib. Однако для человека, впервые знакомого с Matplotlib, сложно выполнить преобразование данных в визуальные эффекты.
Контекст в объяснительном подходе является решением этого препятствия. Написав процедуру через призму реального примера, мы демонстрируем понимание среды, в которой работает пользователь. Это улучшает взаимоотношения документации и пользователя с точки зрения достижения цели или ожидания выполнения задачи.
У пользователя есть последовательная производная цель. Например, специалист по данным обувной компании должен представить команде данные о клиентах, чтобы проиллюстрировать тенденции покупок с течением времени. В этой ситуации пользователь должен научиться ориентироваться в Matplotlib и использовать инструменты библиотеки для выполнения поставленной задачи.
Благодаря дополнительному контексту для поддержки документации новый пользователь может лучше понять тему. Производная цель пользователя параллельна документации. Я надеюсь работать над тем, что ведущий разработчик Том Касвелл обсуждал в интервью в 2017 году: «Наличие человека, который действительно может писать и сочувствует пользователям, пройдёт и, по сути, напишет 200-страничную книгу «Введение в Matplotlib» и Пусть это будет основной записью в документации».
Альтернативный подход к написанию разъяснительных статей
Текущая документация демонстрирует возможности Matplotlib, то есть то, что пользователь может делать с библиотекой. Например, руководство часто следует шаблону, который не предполагает объяснения основного метода.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Часто при наличии документации по программированию и поддержке пользователю рекомендуется запустить код самостоятельно, чтобы понять, что происходит. Хотя образ мышления программирования улучшает понимание пользователем темы, кривая обучения преобразованиям имеет мало вспомогательного содержания. Это может оказаться непростой задачей, поскольку документация ограничена.
Предоставление дополнительных диаграмм, изображений или других наглядных материалов поможет создать новые возможности для обучения. Приведенная ниже структура также может служить шаблоном для нового контента. Кроме того, добавление нетекстовых изображений или графики может выиграть от таких функций, как выноски и пометки. Бывают случаи, когда по изображениям труднее ориентироваться без указания того, как и где код преобразуется в исполняемый результат. Я считаю, что не хватает сильного визуального элемента, который мог бы способствовать лучшему пониманию тем.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Этот альтернативный подход к использованию пояснительного письма для документации обладает огромным потенциалом. Когда пользователи увидят различные концепции преобразований, они смогут лучше определить основные стратегии разработки визуализаций данных. Эти знания могут помочь пользователям внедрять инновации и использовать преимущества функций, представленных примерами, основанными на реальных сценариях использования.
По мере роста популярности Matplotlib постоянство простоты использования и доступности являются свидетельством репутации библиотеки. Эти характеристики позволяют продемонстрировать шаблоны и общие стратегии, которые могут проявляться не только в коде, но и в документации. Если Matplotlib является простым и стандартным для программирования пользователями, о чем свидетельствует его растущее использование и расширение ресурсов, то же самое можно сказать и о технической документации.
Когда пользователи сталкиваются с проблемами, они обычно используют поиск для их решения. Вместо того, чтобы полагаться на поиск как на основной метод навигации, может оказаться более эффективным, если пользователи создадут свою собственную учебную программу в документации. В этом смысле пользователь ищет решение своей проблемы, а затем, когда он сталкивается с другой проблемой или ему нужна дополнительная информация, он будет использовать встроенные и подробные ссылки повсюду.
Это потребует восходящей архитектуры организационной системы. Для каждой темы в Matplotlib богатая сеть ссылок на тематические темы, а также информационные темы помогут построить надежную сеть. В этой сети пользователь с большей вероятностью продолжит использовать документацию по мере перехода к своей теме и изучения все большего и большего количества информации, связанной с этой темой.
Препятствия
Всегда возникают проблемы с таким всеобъемлющим и подробным проектом, как этот. Как новичок в отрасли, я имею ограниченный опыт использования Sphinx и ReST для написания документации. Я также новичок, когда дело касается Matplotlib и Git. Чтобы освоить эти четыре системы и привыкнуть к их использованию для сотрудничества и исследований, потребуется время. Мне нужно будет делегировать время на этапе объединения сообщества и ранее, чтобы заложить необходимую основу для путей начального уровня. В течение этого времени, если у меня возникнут проблемы с концепциями и основами, мне нужно будет обратиться к сообществу за дополнительной поддержкой.
Координация совместных усилий в разных часовых поясах и на онлайн-платформах также потребует некоторых корректировок. Существует множество способов общения, которыми пользуются люди во всей отрасли, поэтому важно убедиться, что я доступен и доступен во всех средах. Я буду прозрачен в своей расстановке приоритетов в отношении различных ожиданий. Хотя я только начинаю выполнять подобную работу в отрасли, я стараюсь нести ответственность и быть открытым для отзывов и критики. Я считаю, что эти качества ценны независимо от области.
Кроме того, расширение юзабилити-тестирования — это раздел документации, который, по моему мнению, принесет пользу путям входа в Matplotlib. Проведение опросов на предмет удобства использования контента служит цели предоставления профиля пользователя, то есть личности. Ценна такая информация, как опыт пользователя, его отрасль и история устранения неполадок. Эти фрагменты помогают сформировать язык, лежащий в основе процедуры. Когда письмо встречается с читателями на их уровне, содержание становится более зрелым и выходит за рамки исключительно обучающего.
Большие трудности часто возникают при создании постоянной практики тестирования юзабилити. Слишком часто бывает, чтобы во время разработки контента проводилось хотя бы одно тестирование, если оно вообще проводилось. Регулярное тестирование юзабилити помогает улучшить повествование контента. Я надеюсь составить график или регулярно проводить тесты удобства использования с сообществом Matplotlib.
Заключение
У меня есть небольшой опыт использования Python, а также Matplotlib в свободное время. То, чему я научился за последние несколько месяцев, произошло благодаря текущей документации и моему собственному любопытству. За это время у меня было несколько видео и наставников. Мне еще предстоит многому научиться и еще больше возможностей для совершенствования, поскольку я создаю свою собственную учебную программу по программированию, которая меня интересует.
Увидев идеи, которые Matplotlib и сообщество имеют для GSoD, я чувствую, что это будет отличный опыт для улучшения моих навыков технического писателя и получения возможности узнать больше от людей, стоящих за кулисами. Я почувствовал, что этот проект Matplotlib одновременно значим и является тем, что мне нравится в идеологии.
В работе над пересмотром руководства по использованию моя цель как технического писателя — помочь пользователям выполнить те задачи, которые они хотят, не перегружая их доступными функциями. Я считаю, что лучшая документация будет продолжать расти и адаптироваться к пользователям и позволит любому пользователю перейти к своим собственным решениям.