Проект Боке

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

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

Организация с открытым исходным кодом:

Боке

Технический писатель:

vis_verborum

Название проекта:

Создание, чтение, обмен: оптимизация документации Bokeh

Длина проекта:

Стандартная продолжительность (3 месяца)

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

Создание, чтение, обмен: оптимизация документации Bokeh

1. Аннотация

Bokeh — чрезвычайно мощный инструмент для создания интерактивных браузерных визуализаций с помощью Python. Он имеет значительную базу пользователей (502 тыс. загрузок Conda в месяц, 855 тыс. загрузок PyPi) и большое количество участников (455 участников на GitHub). Неудивительно, что обширная документация Bokeh выросла органично. И поэтому местами противоречиво, труднодоступно и запутанно.

Сезон документов Google предоставляет уникальную возможность целенаправленного анализа и пересмотра структуры и содержания документации Bokeh, а также убедиться в том, что документация, связанные с ней инструменты и рабочие процессы пригодны для будущего.

Я кодировал и документировал проекты с открытым исходным кодом с помощью Python и Sphinx (последний раз: PyZillow и PyPresseportal ). Но что делает меня уникальным участником «Сезона документов Google», так это мой журналистский опыт: я проработал в отделах новостей более 13 лет, из них много лет работал управляющим редактором и сторонником цифровых изменений. Помимо моих журналистских обязанностей, у меня было все больше обязанностей по разработке и документированию новых цифровых инструментов и руководств по стилю, а также по обучению сотрудников редакции.

После недавнего переезда из Европы в США я решил изучить новые способы объединения моего энтузиазма в области общения и программирования. Я обнаружил, что техническое письмо — это оптимальное сочетание моих навыков и опыта в писательстве и технологиях. В этом предложении я расскажу, как я буду использовать Season of Docs от Google для оптимизации документации Bokeh: делая создание документации и участие в ней более удобным, делая чтение документации более простым и упрощая обмен информацией в документации с другими.

2. Текущая ситуация

Официальная документация Bokeh состоит из следующих основных блоков:

• Описательная документация: Руководство по установке, Руководство пользователя, Руководство разработчика, Примечания к выпуску.
• Галерея и демо (интерактивные примеры с исходным кодом)
• Справочное руководство (документация на основе строк документации)
• Учебное пособие (обширная коллекция блокнотов Jupyter, размещенная на mybinder.org)
• Строки документации и справка по модели для IDE
• Примеры и README в репозитории проекта.

Кроме того, большой объем информации доступен на форуме поддержки Bokeh и на Stack Overflow, где разработчик Bokeh активно отвечает на вопросы пользователей, а также в блоге Bokeh Medium.

Большинство веб-страниц документации созданы с помощью Sphinx с использованием нескольких стандартных и пользовательских расширений Sphinx. Например, Справочное руководство создается на основе строк документации с использованием таких расширений, как «autodoc» и специального «bokeh_autodoc». Как и положено органично созданной документации, она содержит избыточность и несоответствия.

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

Например:

• Использование существительных, герундий и необычных слов вместо ясных и сильных глаголов делает часть текста излишне усложненной: «Основное наблюдение состоит в том, что типичное использование предполагает создание сюжетных объектов с помощью функцииfig()» . Это следует перефразировать, чтобы облегчить чтение. Например: «Функцияfigure() — это функция, наиболее часто используемая для создания объектов графика».
• Некоторые предложения очень длинные, что затрудняет их понимание: «Далее мы можем вызвать vbar со списком факторов названия фруктов в качестве координаты x, высотой панели в качестве верхней координаты и, при необходимости, любой шириной или другими свойствами, которые мы хотели бы изменить. набор" . Более длинные предложения следует разбивать на более короткие предложения или маркированные списки. Упрощение предложений будет особенно полезно для пользователей с дислексией или людей, которые не используют английский в качестве родного языка (см. проблему № 10160 ).
• Непоследовательное использование «вы» и «мы», что сбивает с толку и отвлекает: «Есть два основных метода, которые можно использовать в зависимости от вашего варианта использования» и «Мы можем построить все годовые ряды, используя отдельные вызовы» (два примера с той же страницы ). Некоторые страницы обращаются к читателям даже по-разному, например: «пользователям, возможно, придется установить дополнительные зависимости» или «можно создавать более сложные макеты» .
• Опечатки, пропущенные и лишние слова, а также грамматические ошибки прерывают поток чтения и подрывают достоверность информации: «Боке упрощает создание базовых гистограмм» или «См. раздел «Глифы» в Руководстве пользователя» .
• Структурные несоответствия могут расстраивать читателей: например, наличие хорошо аннотированных примеров на одной странице и отсутствие пояснений к примерам на другой странице .

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

3. Цели

Чтобы наиболее эффективно использовать одиннадцатинедельный этап разработки документации, я сосредоточусь на трех ключевых элементах:

3.1. Улучшите создание документов

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

Я гарантирую это двумя способами:

• Я создам набор практичных и простых рекомендаций по стилю , которые будут включены в существующее Руководство разработчика. Эти рекомендации будут касаться стиля, грамматики и структуры. Кроме того, я буду использовать внутренние каналы связи, такие как Slack, чтобы убедиться, что участники Bokeh осведомлены о правилах стиля. Я также проведу индивидуальное обучение и сеансы вопросов и ответов для команды.
• Я буду работать с основной командой над поиском оптимального набора инструментов для контроля качества документации , который будет добавлен к существующим рабочим процессам Bokeh для PR (pull request) и CI (непрерывная интеграция). В зависимости от требований команды это может означать добавление таких инструментов, как проверка орфографии pydocstyle , proseint или sphinxcontrib, в набор тестов Bokeh, настройку перед фиксацией или действия GitHub. Я добавил рабочее доказательство концепции к действиям GitHub одного из моих собственных проектов с открытым исходным кодом .

3.2. Улучшите чтение документации

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

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

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

Как и в случае с улучшением создания документов, описанным выше, я сосредоточусь на том, чтобы заложить основу для будущих улучшений и постоянно высоких стандартов документации Bokeh.

3.3. Улучшите обмен документами

Все больше и больше дискуссий вокруг Боке происходит на сторонних платформах. Многие из этих платформ используют метаданные, такие как OpenGraph от Facebook, для включения расширенного предварительного просмотра ссылок. OpenGraph используется такими сервисами, как Facebook, Twitter, LinkedIn, Slack и iMessage. Форум Bokeh's Discourse также использует OpenGraph для предварительного просмотра ссылок.

Чтобы использовать эту технологию, я добавлю метаданные на веб-страницы, созданные Bokeh Sphinx, как описано в выпуске №9792 . Наиболее эффективным способом будет использование специального расширения Sphinx. Несколько дней назад на GitHub была опубликована самая первая версия расширения Sphinx для данных OpenGraph. Я буду использовать некоторые этапы разработки документации, чтобы улучшить это расширение для использования с документацией Bokeh.

Я также создал доказательство концепции, которую успешно использую в одном из моих собственных проектов с открытым исходным кодом, PyPresseportal . Это расширение автоматически собирает соответствующую информацию, такую ​​как заголовок, описание, изображение и URL-адрес. Затем он вставляет эту информацию в сгенерированный Sphinx HTML-код в виде тегов OpenGraph.

Следующим шагом в разработке этого расширения будет введение пользовательских директив для ручного определения метаданных OpenGraph (аналогично существующим «мета» директивам docutil). Автоматически сгенерированные метаданные будут использоваться только в качестве запасного варианта, если данные, введенные вручную, недоступны.

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

Члены сообществ Sphinx и ReadTheDocs выразили заинтересованность в разработке расширений для OpenGraph и структурированных данных (например, в выпусках #1758 и #5208 ), и я обязательно буду тесно с ними сотрудничать.

4. Результаты

Подводя итог, я ожидаю, что в результате Season of Docs будут получены следующие результаты:

• Рекомендации по стилю документации для авторов Bokeh
• Пересмотрены рабочие процессы PR и CI, включившие автоматизированный контроль качества документации.
• Отредактированное и переработанное Руководство пользователя.
• Пересмотренная целевая страница документации
• Метаданные OpenGraph, включенные в веб-страницы документации и рабочее расширение Sphinx.

Кроме того, я веду «документальный журнал», чтобы документировать свое путешествие по Сезону документов Google на своем личном веб-сайте/Medium или в блоге Bokeh's Medium. Это также послужит основой для отчета о проекте для Google. Я буду выполнять всю работу прозрачно, в виде проблем на GitHub и запросов на включение, когда это возможно.

5. Сроки

Перед этапом объединения сообщества: я уже активно участвую в нескольких дискуссиях в репозитории Bokeh на GitHub и общаюсь с Брайаном Ван де Веном и Павитрой Эсварамурти, наставниками Bokeh в Google Season of Docs. Я буду активно участвовать в разговоре о боке, а также буду дальше знакомиться с ним, создавая и публикуя визуализации.

Фаза объединения сообществ (17.08 - 13.09):

• Познакомьтесь с основной командой, уточните план проекта в обмене с наставниками
• Настройте график и каналы связи для регулярной отчетности и обратной связи с наставниками.
• Будьте активны в Bokeh's Slack, чтобы информировать всех заинтересованных участников Bokeh о сезоне документов Google и целях на этапе разработки документации.
• Соберите отзывы от авторов Bokeh для дальнейшей доработки плана на этапе разработки документа.

Этап разработки документа

1 неделя, 14.09 - 20.09:

• Начните аудит и редактирование описательной документации.
• Начать разработку рекомендаций по стилю

2 неделя, 21.09 - 27.09:

• Продолжить работу над рекомендациями по стилю.
• Продолжить редактирование описательной документации
• Начните перерабатывать целевую страницу документации.

3-я неделя, 28.09 - 04.10:

• Завершить разработку рекомендаций по стилю
• Доработка целевой страницы документации

Неделя 4, 05.10 - 11.10:

• Завершить редактирование описательной документации
• Обсудите с основной командой Bokeh вопросы интеграции инструментов контроля качества документов в рабочие процессы PR/CI.

Неделя 5, 12.10 - 18.10:

• Организуйте сессию вопросов и ответов с участниками Bokeh в Slack, чтобы обсудить рекомендации по стилю, улучшения повествовательной документации и рабочие процессы PR/CI.
• Начать разработку существующего доказательства концепции метаданных OpenGraph в развертываемое расширение Sphinx.
• Пересмотреть рекомендации по стилю на основе отзывов участников сеанса вопросов и ответов с авторами Bokeh.

6 неделя, 19.10 - 25.10:

• Начало тестирования инструментов контроля качества документов в рабочих процессах PR и CI
• Продолжить разработку расширения Sphinx для метаданных.

7 неделя, 26.10 - 01.11:

• Тестирование расширения Sphinx
• Вторая сессия вопросов и ответов с авторами Bokeh в Slack
• Пересмотреть результаты на основе отзывов второй сессии вопросов и ответов.

8-я неделя, 02.11 - 08.11:

• Разверните расширение Sphinx и опубликуйте улучшенную описательную документацию и целевую страницу документации.

9 неделя, 09.11 - 15.11:

• Внедрение инструментов контроля качества документов в рабочие процессы PR и CI.
• Обновить и опубликовать Руководство для разработчиков, включив в него рекомендации по стилю и дополнения к рабочим процессам PR и CI.

Неделя 10, 16.11 - 22.11:

• Завершить оставшиеся задачи

11 неделя, 23.11 - 29.11:

• Начать писать отчет по проекту
• Начать писать оценку проекта

Этап завершения проекта

Неделя 12, 30.11 - 05.12:

• Завершить и представить отчет по проекту

13 неделя, 03.12 - 10.12:

• Завершить и представить оценку проекта

После завершения сезона документации Google:

• Я надеюсь продолжать участвовать в разработке Bokeh и продолжать работать над документацией Bokeh.
• Я планирую продолжить разработку расширения Sphinx для метаданных OpenGraph/Structured Data.
• Я надеюсь использовать свой журналистский опыт и существующую сеть контактов для продвижения Боке как инструмента журналистики данных. Например, написав о боке для журналистской аудитории или предложив доклады на конференциях об использовании боке в журналистской среде.

6. О себе

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

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

Руководства и документы, которые я написал на предыдущей работе, к сожалению, не являются общедоступными. Поэтому сейчас я концентрируюсь на более активном участии в проектах с открытым исходным кодом (примеры см. ниже). В своей работе по написанию технических статей я основывался на руководствах по стилю, таких как руководство по стилю документации для разработчиков Google и руководство по стилю Microsoft. Я регулярно использую GitHub, Slack и Linux. Я писал описательную документацию, а также строки документации и подсказки по типам, используя такие инструменты, как Sphinx, Mypy и Sphinx autodoc.

В настоящее время я работаю фрилансером. Мой график обеспечивает необходимую гибкость для работы над документацией Bokeh примерно 25 часов в неделю на этапе разработки документа. Я работаю в тихоокеанском часовом поясе, но с радостью подстраиваюсь под графики и потребности команды.

7. Недавние примеры документации с открытым исходным кодом

• PyZillow : PyZillow — это оболочка Python для API сайта недвижимости Zillow.com. Помимо предоставления некоторого кода и работы в качестве одного из его сопровождающих, я написал полную документацию . Я использовал Sphinx для повествовательной документации, а также для справки по модулям. Я создал ссылку на модуль с помощью autodoc расширения Sphinx на основе строк документации, которые я добавил в код.

• PyPresseportal : PyPresseportal — это оболочка Python для API веб-сайта presseportal.de. Веб-сайт presseportal.de является одним из крупнейших распространителей пресс-релизов и объявлений по связям с инвесторами в Германии. Например, почти все полицейские и пожарные службы используют этот сервис для распространения своих пресс-релизов. После многих лет использования API в качестве журналиста я решил разработать интерфейс Python для доступа к обширным ресурсам данных веб-сайта в виде объектов Python. Я написал код и всю документацию по Sphinx.