Skip to main content

Ведущий разработчик Matplotlib объясняет, почему он не может исправить документацию, в отличие от вас

Интервью с Томом Касуэлем, ведущим разработчиком Matplotlib

Том Касуэлл

Учитывая недавний всплеск популярности проектов в области научных исследований с открытым исходным кодом, таких как pandas, NumPy и Matplotlib, - вероятно, никого не удивляет, что повышенный уровень интереса вызывают жалобы пользователей на документацию. 

Чтобы пролить свет на то, что поставлено на карту, мы планировали поговорить с кем-то, кто знает много о предмете: Томас Касуэлл, ведущий разработчик Matplotlib. 

Matplotlib - гибкий и настраиваемый инструмент для создания статических и интерактивных визуализаций данных, он существует с 2001 года и является основополагающим проектом в научном стеке Python. Matplotlib стал спонсируемым проектом NumFOCUS в 2015 году.

Том работает над Matplotlib последние пять лет и начал отвечать на вопросы о проекте в Stack Overflow. Ответы на вопросы стали отправкой сообщений об ошибках, для написания патчей, которые стали поддерживать проект... и теперь он является ведущим разработчиком! (Удовлетворительный факт: продвижение Тома через сообщество с открытым исходным кодом следует именно по тому пути, который описал Бретт Кэннон, основной разработчик Python).

Директор по коммуникациям NumFOCUS Джина Хелфрих недавно встретилась с Томом, чтобы обсудить проблемы, связанные с управлением документацией по проекту, столь же массовым и фундаментальным, как Matplotlib.

 

«То, что не задокументировано - не существует».

~ Mike Pope

GH: Большое спасибо за то, что нашли время поговорить с нами о Matplotlib и документации с открытым исходным кодом, Том! Чтобы немного рассказать о нашем разговоре, можете ли вы немного рассказать о своем недавнем прошлом и будущем с Уэсом МакКинни о пандах и жалобах пользователей на документацию?

TC: Я только видел края, но вижу обе стороны.

С одной стороны, я думаю, что, по словам Майка Поупа, «то, что не документировано, не существует». Если вы пишете инструменты с открытым исходным кодом, часть этого документа четко документирует их, дабы пользователи могли обнаружить и фактически использовать, не доходя до источника [кода]. Этого не достаточно, чтобы просто сбрасывать код в Интернете - вам нужно все это сделать.

С другой стороны, если вы не платите [за программное обеспечение], вы не можете предъявлять требования. Отношение, которое, как мне кажется, относится к Уэсу, заключается в следующем: «Вы создали этот инструмент, который мне нужен, поэтому я ожидаю платную поддержку корпоративного уровня, потому что это явно важно для моей работы».

Но я думаю, что Эрик О Лебиго отвечал на первую часть. Часть создания инструмента - это документация, а не только код. Но Уес отвечает на право, на ожидание свободной работы. Поэтому я вижу обе стороны.

GH: В частности, глядя на Matplotlib, который сталкивается со многими из тех же проблем, что и панды, я знаю, что у вас есть большие проблемы с вашей документацией. У меня создалось впечатление, что есть такое понятие от новых пользователей, что начало работы с Matplotlib является супер разочаровывающим, и документы действительно не помогают. Можете ли вы рассказать мне об истории там и о том, как у проекта возникла эта проблема?

TC: Итак, Matplotlib - это обширная библиотека. Я работаю над ним в течение 5 лет и, возможно, раз в месяц или через месяц, есть отчет об ошибке, где моя первая реакция: «Подождите ... мы что делаем?»

И многое из этого недостаточно документально. В библиотеке сохранилось не менее двух поколений частичного преобразования в стандартизированные форматы docstring. Насколько я понимаю (потому что в то время меня не было), мы были одним из первых проектов за пределами основного Python, чтобы принять Sphinx для создания наших документов, возможно, слишком рано. У нас много странных настроек, так как Sphinx еще не делал их [в то время]. С тех пор другие люди создали лучшие версии, но поскольку Matplotlib настолько огромен, что их трудно переносить.

Я думаю, что если вы создадите PDF-версию наших документов, это будет как 3000 страниц, и я бы сказал, что в библиотеке может быть половина документации, которая действительно нужна.

Мы крайне недооценены, в том смысле, что не все имеет хорошие документы. С другой стороны, мы задокументированы тем, что то, что мы имеем, плохо организовано, и нет четкой точки входа, и если вы хотите узнать, как что-то сделать, мне даже трудно найти, где что-то документируется. И если у меня[Ведущий разработчик] есть проблемы с поиском, просто нет новой молитвы новых пользователей. Таким образом, в этом смысле мы оба сильно задокументированы и сильно задокументированы.

GH: Учитывая, что Matplotlib больше 15 лет, есть ли у вас ощущение того, кто писал документы? Как ваша документация действительно развивается?

TC: Исторически, очень похожи на код, документация была органически развита. У нас было много инвестиций в примеры и docstrings, и несколько вещей, обозначенных как учебники, которые учат вас одному конкретному навыку. Например, у нас есть проза по «грубой теории цветовых карт» и как сделать цветовой код.

Многие документы Matplotlib являются примерами, и примеры перекрываются. За последние несколько лет, когда я вижу интересные примеры в списке рассылки или в переполнении стека, я скажу: «Можете ли вы поместить этот пример в документы?», И он пойдет где-нибудь в примерах. Итак, я думаю, что я активно помогал проблеме, что слишком много вещей, чтобы пробраться.

Некоторые из них, люди будут делать 6-часовое учебное пособие, а затем некоторые из этих примеров попадут в документы. И тогда кто - то еще сделает 6-часовой учебник (вы не можете охватить всю библиотеку через 6 часов), и основы, вероятно, похожи, но они могут отформатировать его по-другому.

GH: Ого, это звучит довольно сложно, чтобы наследовать и пытаться поддерживать. Какие улучшения вы работали над документацией?

TC: За последние пару лет было предпринято усилие, чтобы перейти в формат numpydoc, вдали от ранее разработанной нами модели. Кроме того, Nelle Varoquaux недавно проделала огромную работу и приложила все усилия, чтобы перейти от того, как мы делали примеры с использованием Sphinx Gallery, что значительно упрощает использование хорошей прозы в примерах. Недавно он был поднят Крисом Холдграфом. Он будет работать в наших основных документах с Matplotlib 2.1, что будет большим улучшением для пользователей. Нелле также организовал распределенный Докатон.

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

GH: Если бы вы могли махать волшебной палочкой и иметь документы Matplotlib, которые вы хотите, как бы это выглядело?

TC: Ну, как я уже упоминал, документы выросли органично, и это означает, что у нас нет последовательного голоса. Это также означает, что для разных вещей нет единственной точки истины. Когда вы пишете пример, как далеко позади вы идете? Поэтому не понятно, что вам нужно знать, прежде чем вы сможете понять пример. Либо вы объясните достаточно, так и назад (так что у нас есть случайный ассортимент основ, размазанных повсюду), или у вас есть только примеры, которые, если вы уже не являетесь тяжелым пользователем, просто не имеют смысла.

Итак, чтобы ответить на вопрос, имея кого-то, кто может писать и есть сочувствие для пользователей, пройти и в основном написать 200-страничную книгу «Intro to Matplotlib», и это будет основной вход в документы. Это мое настоящее видение того, что я хочу.

GH: Если бы вы сегодня вводили нового пользователя в Matplotlib, что бы вы прочитали? Где бы вы указали ей в документах?

TC: Ну, нет ничего хорошего и ясного: «Вам сказали, что вам нужно использовать Matplotlib. Пойдите, проведя день и прочитайте это. «Я не уверен, где бы я указал людям на это прямо сейчас. Николя Ружье написал очень хорошие вещи, некоторые из которых перешли в документы.

Там много чего, но он не сопоставлен централизованно или связан с нашими документами как «НАЧАТЬ ЗДЕСЬ». Я также должен добавить, что у меня может не быть лучшего представления об этом больше, потому что я не активно его искал, поэтому, возможно, Я просто не нашел его, потому что мне это не нужно. Я не знаю, что он существует. [Это действительно появилось недавно в списке рассылки.]

Место, куда мы направляем людей, - посмотрите галерею и нажмите на миниатюру, которая будет ближе всего к тому, что вы хотите сделать.

Бен Рут несколько раз представил анатомию учебника Matplotlib в SciPy. Существует несколько книг Matplotlib, которые существуют. Смешивается, были ли авторы участниками (в проекте). Недавно Бен Рут написал об интерактивных фигурах. Я подошел и несколько раз перевернул его, просто потому, что у меня нет времени писать книгу. Поэтому моя мысль о том, чтобы получить технического писателя, заключалась в том, чтобы написать техническому писателю, чтобы написать книгу, и вместо того, чтобы публиковать ее как книгу, поместите ее в онлайн-документы.

GH: Есть ли кто-нибудь в сообществе разработчиков Matplotlib, который «специализируется» на части документации или имеет много прав на документацию?

Нелл делала это для Матплотлиба немного, но отступила. Крис Холдграф сейчас возглавляет некоторые связанные с документом вещи. Николай Ружье написал ряд замечательных уроков за пределами проектной документации.

Я имею в виду, что никто не использует только Matplotlib. Вы не используете нас, но не используете SciPy, NumPy или панды. Вы должны использовать что-то еще, чтобы выполнить фактическую работу, которую теперь вам нужно визуализировать. Есть много «чистых» представлений в Matplotlib в других местах. Например как новый Джейк VanderPlas по анализу книги и Katy Huff и Энтони Скопац годов книги есть введение в Matplotlib, которые покрывают его в той степени, по их мнению , было необходимо для их целей.

GH: Мне бы хотелось услышать ваши мысли о роли переполнения стека во всем этом.

TC: На самом деле это то, как я попал в проект. Мой номер переполнения стека большой, и это почти все вопросы Matplotlib. И как я начал, я ответил на вопросы, а затем много вопросов о переполнении стека: «Пожалуйста, прочитайте документы для меня». Что, отлично. Но на самом деле отличный способ изучить библиотеку - ответить на вопросы о переполнении стека, потому что люди, у которых есть проблемы, которые у вас есть лично, спросят: «Как это сделать?», И теперь вам нужно выяснить, как сделай это. Это весело.

Но иногда люди задают вопросы, и на самом деле они обнаружили ошибку. И в определении того, что они на самом деле обнаружили ошибку, я начинаю пытаться выяснить, как исправить ошибки. Поэтому я начал несколько отчетов; некоторые из них: «Вот запрос тянуть, чтобы исправить найденную мной ошибку». И затем, когда я начал вкладывать много PR, они говорили: «Вам нужно начать их просматривать сейчас», поэтому они дали мне права на совершение и сделали меня просмотрите вещи. И затем они назначили меня ответственным. [смех]

Мне нравится Stack Overflow. В значительной степени я думаю, что он заменен списком рассылки. Если бы у меня возникла какая-либо критика «Переполнения стека», я думаю, что это убеждает людей, которые отвечают на вопросы, чтобы продвинуть больше вещей.

В Stack Overflow есть некоторые вещи, которые являются очень хорошими примерами. Например, сложная вещь: вам нужно прикоснуться к этим 7 различным функциям, каждый из которых относительно полностью задокументирован, но вы должны собрать их правильно. Некоторые из этих ответов, вероятно, должны появиться в галерее с аннотациями от нас о том, как это работает. В принципе, если вы пройдете через 50 ответов Джо Кингтона, они должны, вероятно, все просто пойти в документы.

Другие, вопрос задается, потому что докстрина просто не ясна. И те, если бы вы могли убедить людей, которые отвечали на эти вопросы, использовать его в качестве основного обзора «где наша документация непонятна?» И вместо того, чтобы просто отвечать на него [на переполнении стека], чтобы переместить это назад [в документы].

GH: Как это похоже на управление PR для документации, а не исправления и исправления?

Мы попытались упорядочить работу с PR-документами. С другой стороны, написание PR-документов docs - самая болезненная вещь в открытом доступе, потому что вы получаете копирование по запросу pull. Вы получаете придирчивое, корректурное копирование через комментарии GitHub. Например, «есть недостающая запятая» или «два пробела!» И снова я продолжаю использовать себя как странный ориентир по выбросам, но я унываю, когда пишу документы для запросов, а затем получаю 50 комментариев придирчивых мелочей.

То, что я начал пытаться подтолкнуть, как порог в документах, заключается в следующем: «Ухудшилось ли это?» Если бы это не усугубило, слейте его. Часто, оставляя комментарий GitHub, требуется больше времени, чем исправлять его.

 

«Если вы можете использовать Matplotlib, вы можете участвовать в нем»

~ Tom Caswell, ведущий разработчик Matplotlib

 

GH: Какое действие вы хотели бы, чтобы члены сообщества читали это интервью? Каким образом они могут повлиять на эту проблему?

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

Если вы пользователь, и вы что-то читаете docstring, и это не имеет смысла, а затем вы немного поиграете, и вы это понимаете, и вы хорошо понимаете эту функцию, чтобы использовать ее, - если бы люди могли начать уточняя докстерии.

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

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

GH: Это замечательное сообщение. Спасибо, что поговорили со мной, Том!

TC: Пожалуйста. Спасибо.