Colaboradores do WordPress buscam patrocínio para melhorar os documentos do desenvolvedor do Gutenberg

Os desenvolvedores do WordPress Milana Cap e Jonathan Bossenger estão iniciando uma campanha de arrecadação de fundos para melhorar a documentação do desenvolvedor do Gutenberg. A conversa começou ontem quando Cap twittou sobre como a documentação é frequentemente negligenciada quando as empresas contratam colaboradores em tempo integral para trabalhar no WordPress.

“Quando sua comunidade não consegue aprender seu software, você não tem colaboradores”, disse Cap. “Documentação e tutoriais são muito mais importantes para projetos de software de código aberto do que as pessoas imaginam.”

A primeira vez que Cap começou a pedir a documentação de Gutenberg foi na Cúpula da Comunidade em Paris, em 2017. Ela vem tentando direcionar a atenção da comunidade para isso desde então.

“Há muitos buracos na documentação do editor de blocos para desenvolvedores, mas o mais óbvio é como começar”, disse Cap. “O início da documentação para desenvolvedores não diz nada sobre como começar. “Diz apenas o que você pode fazer com um bloco, mas não _como_. Desenvolvedores juniores, desenvolvedores somente PHP e qualquer pessoa para quem essa documentação se destina, não sabe como o código de um bloco se parece, onde colocá-lo, como incluí-lo etc., muito menos como construir um bloco personalizado com componentes personalizados e definições."

Parte do desafio de documentar o editor de blocos é que ele está em desenvolvimento ativo. Aprimoramentos e refinamentos são constantemente enviados para o plug-in Gutenberg e acompanhar o que está ou não disponível atualmente no núcleo nem sempre é fácil. Como o WordPress está introduzindo em breve a pesquisa de diretório de blocos, é um bom momento para formalizar a documentação de criação de blocos.

“Exemplos de código estão faltando de forma alarmante em todos os documentos”, disse Cap. “Os exemplos mais básicos existem, mas falta como construir algo utilizável. Então, nesta primeira página, somos enviados para um tutorial, mas esse tutorial não é otimizado para pessoas que nunca construíram um bloco antes. Seguindo isso, eu tenho e não conseguirei construir o bloco.”

Marcus Kazmierczak e uma equipe de contribuidores de documentação estão tentando reconstruir o tutorial no manual oficial do editor de blocos. Um problema do GitHub focado em abordar lacunas na documentação atual do desenvolvedor é o lar de uma discussão ativa sobre a melhor maneira de reescrever os documentos para pessoas que são novas no desenvolvimento de blocos.

“Este é um começo muito bom, mas ainda há muito trabalho a ser feito”, disse Cap. “A documentação completa é escrita por pessoas que conhecem e entendem React e Gutenberg, mas são 'amaldiçoadas pelo conhecimento'. Eles não têm muito tempo para gastar em entender o quanto os outros não sabem e em que detalhes a documentação deve ser escrita. Para ser honesto, eu não acho que eles deveriam gastar seu tempo com isso. Temos uma equipe de documentação e estamos dispostos a participar, mas é necessário algum tipo de ponte.”

O problema com a documentação do desenvolvedor do Gutenberg: não é amigável para os recém-chegados

“O 'problema' que vejo com a documentação do editor de blocos é que, ao contrário de outras documentações do WordPress, ele foi escrito para desenvolvedores JavaScript experientes e não voltado para iniciantes”, disse Bossenger. “Também devo salientar que isso não é de forma alguma um tiro para as pessoas que reuniram a documentação atual, e eu aprecio todo e qualquer trabalho que eles fizeram até agora, é apenas uma séria necessidade de uma revisão e algum refinamento. ”

Bossenger disse que no passado o WordPress tornou muito fácil para qualquer pessoa com uma quantidade limitada de conhecimento em PHP construir rapidamente um plugin ou tema usando ganchos de ação e filtro. Foi fácil olhar para o código e entender o que deveria fazer.

“O JavaScript moderno, e especificamente o React, é uma chaleira de peixe muito diferente”, disse Bossenger. “Requer um nível mais profundo de conhecimento de como o React funciona, incluindo novas terminologias e práticas. O JavaScript moderno também pode ser muito confuso, especialmente se esta for a primeira vez que você está vendo coisas como funções de seta ou instruções if menos detalhadas.

“Se o mais próximo que você chegou de trabalhar com JavaScript no WordPress foi usando jQuery, mudar para o desenvolvimento Gutenberg baseado em React ainda requer algum aprendizado de sua parte.”

Depois de fazer dois cursos antes que ele pudesse construir qualquer coisa para o editor, um em React e outro em Gutenberg, Bossenger disse que o atual manual do Block Editor não foi escrito para desenvolvedores sem experiência em React e JavaScript moderno. Ele acredita que precisa de uma reestruturação para explicar melhor os novos conceitos e se adequar a um padrão que seja mais fácil para um novato consumir. Ele destacou o manual do Plugin Developer como um exemplo onde os capítulos seguem uma estrutura e usam terminologia que é mais como um livro de texto, introduzindo lentamente o leitor a novos conceitos.

“Eu diria que seria bem possível para alguém sem nenhum conhecimento de plugin ou PHP, armado com este manual e o Google, construir um plugin simples para atender seus requisitos específicos rapidamente”, disse Bossenger. “Atualmente, o manual do editor de blocos não é propício para isso.”

Bossenger não está sozinho em sua opinião sobre a documentação atual. Peter Tasker da Delicious Brains publicou recentemente um tutorial sobre como criar um bloco Gutenberg personalizado. Mesmo depois de trabalhar com o React em tempo integral no ano passado, ele achou os documentos oficiais do editor de blocos “meio que em todo lugar” e difíceis de analisar.

Depois que Cap comentou sobre a falta de empresas patrocinando trabalho em tempo integral na documentação, Bossenger testou as águas com um tweet perguntando se os dois poderiam arrecadar fundos para melhorar os documentos de Gutenberg.

“Assim como a equipe do editor de blocos (e qualquer outra equipe de criação), a equipe de documentação está com falta de pessoal”, disse Cap. “Não podemos nos dar ao luxo de dedicar poucos membros para primeiro aprender e depois escrever documentação sobre o desenvolvimento com o editor de blocos. Esta é a principal razão para o meu tweet. Você verá contribuidores patrocinados em todo o núcleo, mas não na documentação, e ouso dizer que ambos são igualmente importantes.”

Antes de lançar sua campanha de arrecadação de fundos, Cap e Bossenger planejam examinar a documentação existente, identificar buracos óbvios e identificar perguntas que permanecem sem resposta para aqueles que são novos no desenvolvimento para o editor de blocos.

“Uma vez que temos um plano, podemos prever quanto tempo é necessário para cada parte”, disse ela. “Com este plano, iremos em busca de patrocinadores. Acho que haverá uma opção de doar antes disso, mas nada é certo neste momento.”

Os blocos são a nova fronteira do desenvolvimento do WordPress. Investir em documentação sólida e tutoriais para iniciantes pode ter um grande impacto na expansão do ecossistema de blocos. Isso também beneficia indiretamente os usuários, pois eles acabam com um diretório de blocos mais diversificado para escolher ao personalizar seus sites WordPress.

Bossenger e Cap estão atualmente trabalhando em um plano para os documentos antes de anunciar sua arrecadação de fundos. Enquanto isso, quem quiser contribuir para melhorar a documentação de criação de blocos pode entrar na discussão do GitHub.