Разработчики WordPress Милана Кэп и Джонатан Босенджер начали сбор средств для улучшения документации для разработчиков Gutenberg. Разговор начался вчера, когда Кэп написал в Твиттере о том, как часто компании не обращают внимания на документацию, когда компании нанимают постоянных участников для работы над WordPress.
«Когда ваше сообщество не может изучить ваше программное обеспечение, значит, у вас нет участников», – сказал Кэп. «Документация и учебные пособия гораздо важнее для проектов ПО с открытым исходным кодом, чем люди думают».
Впервые Кэп начала запрашивать документацию для Гутенберга на саммите сообщества в Париже в 2017 году. С тех пор она пытается привлечь к ней внимание сообщества.
«В документации редактора блоков для разработчиков есть много дыр, но наиболее очевидная из них – с чего начать», – сказал Кэп. «Начало документации для разработчиков ничего не говорит о начале работы. «Здесь говорится только о том, что вы можете делать с блоком, но не как. Младшие разработчики, разработчики только для PHP и все, для кого предназначена эта документация, не знают, как выглядит код блока, где его разместить, как включить и т.д., не говоря уже о том, как создать собственный блок с пользовательскими компонентами и настройки. ”
Отчасти проблема документирования редактора блоков заключается в том, что он находится в активной разработке. В плагин Gutenberg постоянно вносятся улучшения и уточнения, и отслеживать, что в настоящее время доступно, а что нет в ядре, не всегда легко. Поскольку WordPress неизбежно вводит поиск по каталогам блоков, сейчас хорошее время для формализации документации по созданию блоков.
«К сожалению, примеры кода отсутствуют во всех документах», – сказал Кэп. «Самые простые примеры существуют, но не хватает того, как на самом деле создать что-то пригодное для использования. Итак, на этой первой странице мы отправляемся в учебное пособие, но оно не оптимизировано для людей, которые никогда раньше не строили блоки. Следуя ему, я построил и не смогу построить блок ».
Маркус Казмерчак и команда разработчиков документации пытаются перестроить учебное пособие в официальном руководстве редактора блоков. Проблема GitHub, направленная на устранение пробелов в текущей документации для разработчиков, является домом для активного обсуждения того, как лучше всего переписать документацию для людей, которые плохо знакомы с блокировкой разработки.
«Это очень хорошее начало, но предстоит еще много работы», – сказал Кэп. «Полная документация написана людьми, которые знают и понимают React и Gutenberg, но« прокляты знанием ». У них не так много времени, чтобы понять, насколько другие не знают и в каких деталях следует писать документацию. Честно говоря, я не думаю, что им следует тратить на это время. У нас есть группа документации, и мы готовы вмешаться, но необходим какой-то мост ».
Проблема с документацией разработчиков Gutenberg: она не подходит для новичков
«Проблема», которую я вижу в документации редактора блоков, заключается в том, что, в отличие от другой документации WordPress, она написана для опытных разработчиков JavaScript, а не нацелена на новичков, – сказал Босенджер. «Я также должен отметить, что это ни в коем случае не выстрел в людей, которые собрали текущую документацию, и я ценю любую работу, которую они проделали до сих пор, она просто серьезно нуждается в обзоре и некоторой доработке. ”
Босенджер сказал, что в прошлом WordPress позволял любому человеку с ограниченным объемом знаний PHP быстро создать плагин или тему с помощью хуков действий и фильтров. Было легко посмотреть на код и понять, что он должен делать.
«Современный JavaScript, и в частности React, – это совсем другое дело», – сказал Босенджер. «Это требует более глубоких знаний о том, как работает React, включая новую терминологию и методы. Современный JavaScript также может сбивать с толку, особенно если вы впервые видите такие вещи, как стрелочные функции или менее подробные инструкции if.
«Если вы ближе всего к работе с JavaScript в WordPress использовали jQuery, переход на разработку Gutenberg на основе React все еще требует некоторого обучения с вашей стороны».
Пройдя два курса, прежде чем он смог создать что-либо для редактора, один на React, а другой на Gutenberg, Босенджер сказал, что текущее руководство по редактору блоков не написано для разработчиков, не имеющих опыта в React и современном JavaScript. Он считает, что его нужно реструктурировать, чтобы лучше объяснить новые концепции и соответствовать шаблону, который новичку легче усвоить. Он выделил руководство разработчика плагинов в качестве примера, в котором главы следуют структуре и используют терминологию, которая больше похожа на учебник, постепенно знакомя читателя с новыми концепциями.
«Я бы сказал, что для человека, не имеющего знаний о плагинах или PHP, вооруженном этим руководством и Google, вполне возможно быстро создать простой плагин, удовлетворяющий своим конкретным требованиям», – сказал Босенджер. «В настоящее время руководство редактора блоков не способствует этому».
Босенджер не одинок в своем мнении о текущей документации. Питер Таскер из Delicious Brains недавно опубликовал руководство по созданию собственного блока Гутенберга. Даже после постоянной работы с React в течение прошлого года он обнаружил, что официальные документы редактора блоков «повсюду» и их трудно разбирать.
После того, как Кэп прокомментировал отсутствие компаний, спонсирующих постоянную работу над документацией, Bossenger проверил воду, написав твит, и спросил, смогут ли они вдвоем собрать средства для улучшения документации Gutenberg.
«Так же, как команда редактора блоков (и любая другая команда Make), команда документации недоукомплектована», – сказал Кэп. «Мы не можем позволить себе выделить несколько участников, чтобы сначала изучить, а затем написать документацию по разработке с помощью редактора блоков. Это основная причина моего твита. Вы увидите спонсируемых участников повсюду, но не в документации, и я осмелюсь сказать, что оба они одинаково важны ».
Перед запуском своей кампании по сбору средств Кэп и Босенджер планируют просмотреть существующую документацию, выявить очевидные дыры и выявить вопросы, которые остаются без ответа для тех, кто плохо знаком с разработкой редактора блоков.
«Когда у нас есть план, мы можем предсказать, сколько времени потребуется для каждой части», – сказала она. «С этим планом мы будем искать спонсоров. Я думаю, что будет возможность сделать пожертвование и раньше, но на данный момент нет ничего определенного ».
Блоки – это новый рубеж в разработке WordPress. Инвестиции в надежную документацию и учебные пособия для начинающих могут иметь большое влияние на расширение экосистемы блоков. Это также косвенно приносит пользу пользователям, поскольку в конечном итоге они получают более разнообразный каталог блоков на выбор при настройке своих сайтов WordPress.
Босенджер и Кэп в настоящее время работают над планом для документации перед тем, как объявить о сборе средств. А пока любой, кто хочет внести свой вклад в улучшение документации по созданию блоков, может присоединиться к обсуждению на GitHub.
