Авторы WordPress ищут спонсоров для улучшения документации разработчиков Gutenberg

Разработчики WordPress Милана Кэп и Джонатан Боссенгер начинают сбор средств на улучшение документации для разработчиков Gutenberg. Разговор начался вчера, когда Кэп написал в Твиттере о том, как часто упускается из виду документация, когда компании нанимают штатных сотрудников для работы над WordPress.

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

Впервые Кэп начала запрашивать документацию Гутенберга на саммите сообщества в Париже в 2017 году. С тех пор она пыталась привлечь к ней внимание сообщества.

«В документации редактора блоков для разработчиков много дыр, но самая очевидная — с чего начать», — сказал Кэп. «Начало документации для разработчиков ничего не говорит о начале работы. «Здесь написано только то, что вы можете сделать с блоком, но не _как_. Младшие разработчики, разработчики только для PHP и все, для кого предназначена эта документация, не знают, как выглядит код блока, куда его поместить, как включить и т. д., не говоря уже о том, как создать собственный блок с пользовательскими компонентами и настройки."

Часть проблемы документирования редактора блоков заключается в том, что он находится в активной разработке. В плагин Gutenberg постоянно добавляются улучшения и усовершенствования, и отследить, что в настоящее время доступно, а что нет в ядре, не всегда легко. Поскольку WordPress скоро представит поиск по каталогам блоков, самое время формализовать документацию по созданию блоков.

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

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

«Это очень хорошее начало, но предстоит еще много работы», — сказал Кэп. «Полная документация написана людьми, которые знают и понимают React и Gutenberg, но «прокляты знаниями». У них не так много времени, чтобы понять, как много других не знают и в какой подробной документации следует писать. Честно говоря, я не думаю, что им стоит тратить на это свое время. У нас есть группа документации, и мы готовы вмешаться, но необходим какой-то мост».

Проблема с документацией для разработчиков Gutenberg: она неудобна для новичков

«Проблема документации редактора блоков, на мой взгляд, заключается в том, что, в отличие от другой документации WordPress, она написана для опытных разработчиков JavaScript, а не для новичков», — сказал Боссенгер. «Я также должен отметить, что это ни в коем случае не удар по людям, которые составили текущую документацию, и я ценю любую и всю работу, которую они проделали до сих пор, она просто серьезно нуждается в обзоре и некоторой доработке. ”

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

«Современный JavaScript и, в частности, React — это совсем другое дело, — сказал Боссенгер. «Это требует более глубокого знания того, как работает React, включая новую терминологию и практики. Современный JavaScript также может быть очень запутанным, особенно если вы впервые видите такие вещи, как стрелочные функции или менее подробные операторы if.

«Если ближе всего вы подошли к работе с JavaScript в WordPress с помощью jQuery, переход на разработку на основе React Gutenberg все равно потребует от вас некоторого обучения».

Пройдя два курса, прежде чем он смог создать что-либо для редактора, один по React и один по Gutenberg, Боссенгер сказал, что текущее руководство по редактору блоков не написано для разработчиков, не имеющих опыта работы с React и современным JavaScript. Он считает, что требуется реструктуризация, чтобы лучше объяснять новые концепции и соответствовать шаблону, который легче использовать новичку. В качестве примера он выделил руководство для разработчиков плагинов, в котором главы имеют структуру и используют терминологию, больше похожую на учебник, постепенно знакомя читателя с новыми концепциями.

«Я бы сказал, что для человека, не имеющего знаний о плагинах или PHP, вооруженного этим руководством и Google, было бы вполне возможно довольно быстро создать простой плагин, отвечающий их конкретным требованиям», — сказал Боссенджер. «В настоящее время руководство по редактору блоков не способствует этому».

Боссенгер не одинок в своем мнении о текущей документации. Питер Таскер из Delicious Brains недавно опубликовал руководство по созданию пользовательского блока Гутенберга. Даже проработав с React полный рабочий день в течение прошлого года, он обнаружил, что официальная документация редактора блоков «разбросана повсюду» и ее трудно анализировать.

После того, как Кэп прокомментировал отсутствие компаний, спонсирующих работу над документацией на полный рабочий день, Боссенджер прощупал почву, написав в Твиттере вопрос, могут ли они вдвоем собрать средства для улучшения документации Гутенберга.

«Так же, как и команда редакторов блоков (и любая другая команда Make), команда документирования недоукомплектована», — сказал Кэп. «Мы не можем позволить нескольким участникам сначала изучить, а затем написать документацию по разработке с помощью блочного редактора. Это основная причина моего твита. Вы увидите спонсируемых участников по всему ядру, но не в документации, и я осмелюсь сказать, что оба одинаково важны».

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

«Когда у нас есть план, мы можем предсказать, сколько времени потребуется для каждой части», — сказала она. «С этим планом мы отправимся на поиски спонсоров. Я думаю, что будет возможность сделать пожертвование еще до этого, но на данный момент ничего не известно».

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

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