Ao longo dos anos, a documentação do desenvolvedor do WordPress, originalmente o Codex, mas agora o WordPress Code Reference, serviu bem ao projeto. No entanto, existe uma sensação na comunidade de que grande parte da documentação mais recente – por exemplo, as APIs JavaScript e os pacotes provenientes de Gutenberg – tem sido inconsistente e mais difícil de ler e compreender. Os desenvolvedores muitas vezes se encontram navegando em designs e organizações desconectados em vários documentos, guias e manuais para tópicos que podem abranger qualquer coisa, desde a API de shortcodes até WP-CLI.
Em dezembro passado, todo o subdomínio de recursos para desenvolvedores do WordPress.org foi relançado com uma página inicial muito mais intuitiva, navegação coesa e um design moderno. Nos círculos de desenvolvedores e nas redes sociais, o relançamento foi recebido com ótimas críticas, junto com mais do que alguns suspiros de alívio.
Embora o redesenho tenha surgido há quase três meses, ele pertence ao WP Tavern como um marco moderno para o projeto WordPress. Conversei com Nick Diego, um Developer Advocate patrocinado pela Automattic, para saber mais sobre a história por trás do redesenho e o que mais podemos esperar da migração plurianual do WordPress.org para uma nova aparência.
Definindo um escopo de projeto
Se você viu o nome de Nick recentemente, pode ser de seus populares plug-ins do WordPress, como Block Visibility e Icon Block, ou então de seu trabalho no WordPress Developer Blog. A equipe de colaboradores que administra o Developer Blog tem estado ocupada educando os leitores sobre como trabalhar com muitas das ferramentas novas e experimentais que saem do Block Editor. Mas alguns deles também estão nas trincheiras tentando reescrever vinte anos de recursos legados para desenvolvedores, como o trabalho contínuo de Justin Tadlock com o Theme Handbook.
“Um dos grandes focos da minha equipe”, explicou Nick, “era tentar melhorar o Manual do Editor de Blocos e o Manual de Temas. , mas uma das coisas que identificamos desde o início foi que a estrutura e o design do site só pioraram as coisas.” (Vou poupar aos leitores os links para meus numerosos discursos no Twitter e podcasts sobre esse assunto exato.)
Assim que perceberam isso, a equipe foi confrontada com uma escolha. Eles poderiam simplesmente ignorar os problemas com o design desatualizado e continuar atualizando o conteúdo. Eles poderiam repensar completamente a forma como a documentação do desenvolvedor para o projeto foi construída e iniciar uma reestruturação massiva. Ou poderiam continuar trabalhando dentro da arquitetura existente, mas concentrando-se em eliminar as lacunas gritantes no design.
Eles escolheram a terceira abordagem – concentrando-se em redesenhar o que tinham, em vez de tentar defender uma plataforma de documentação inteiramente nova. Isso também liberou mais tempo para continuar atualizando a parte mais importante: o conteúdo.
“Prefiro gastar meu tempo corrigindo [o conteúdo]”, explicou Nick. “Porque então, se chegarmos a um ponto em que queremos re-arquitetar a coisa toda, então será um problema arquitetônico e não um ‘ah, e todo o nosso conteúdo é um problema errado’.”
A equipe começou a trabalhar na atualização do conteúdo e do design em conjunto, e Nick pôde aproveitar sua experiência ajudando na recente reformulação do Showcase no WordPress.org.
Documentação por Contribuição
Uma ressalva importante para a documentação do WordPress é que ela também está aberta a contribuições, assim como o núcleo do WordPress. Isso significa que a estrutura na qual a documentação é escrita, discutida e hospedada precisa estar disponível para qualquer colaborador que possa ajudar.
Parte da documentação, como o Manual do Tema, na verdade publica conteúdo dentro de uma instalação do WordPress. Nick explicou que “é muito difícil contribuir, porque você não pode escrever uma solicitação pull em algum lugar. Você tem que abrir um problema que diz: ‘Ei, há um erro de ortografia aqui’ ou ‘Ei, este parágrafo deve ser alterado ‘ e então algum contribuidor de documentos que tem permissão para entrar e fazê-lo. É extremamente desafiador.”
Se a equipe deseja que o conteúdo seja colaborativo, ela precisa ter alguma conexão com o GitHub, onde a colaboração tende a acontecer. O benefício dessa abordagem é que a documentação do desenvolvedor pode ser um caminho para se tornar um contribuidor do WordPress. Depois de fazer uma pequena solicitação pull para corrigir um erro ortográfico, fica um pouco mais fácil considerar fazer um PR com uma alteração real no código.
“Portanto, temos algumas partes do site [em WordPress]”, disse Nick. “Temos algumas peças que estão no GitHub. Há outras partes que são geradas a partir do código-fonte, outras partes que fazem parte de pacotes. Portanto, é uma configuração muito complicada onde há conteúdo em tantos lugares diferentes, e até mesmo com o material que está em GitHub, vem de vários repositórios.”
Por enquanto, qualquer documentação existente no GitHub tem um link para “Melhorar no GitHub” no rodapé, levando você à sua fonte.
Aprendendo com temas de blocos de construção
Atualizar o site de documentação do desenvolvedor para corresponder à nova linguagem de design lançada no WordPress.org significou migrá-lo de um tema clássico para o mesmo tema pai baseado em bloco subjacente que todos os sites WordPress.org recentemente redesenhados estão usando. O que alguns podem ver como um desafio intransponível, esta equipe viu como uma oportunidade de aprendizado e “dogfooding”.
“A seção de documentação é enorme”, disse Nick, “Como você atualiza isso para um tema de bloco? Então, também olhamos para isso como um projeto onde o Meta aprenderá muito à medida que o processo avança.”
A equipe poderia aproveitar todas as suas experiências de migração de um site enorme – centenas de páginas de conteúdo, algumas de autoria do WordPress, mas muitas delas preenchidas por integrações automatizadas com vários repositórios GitHub – e compartilhar as lições que aprenderiam com a equipe principal isso foi construir o próprio Editor do Site.
Um exemplo com o qual tenho certeza que qualquer desenvolvedor irá se identificar é a questão do controle de versão para um tema de bloco.
“Tudo em ponto org precisa de controle de versão”, explicou Nick. “Portanto, o Editor do Site funciona, mas você precisa sincronizar todas as alterações de volta aos arquivos de modelo do tema. Portanto, há definitivamente alguns desafios que a equipe Meta teve que contornar devido aos requisitos exclusivos do ponto org. Mas é foi um estudo de caso realmente interessante.”
Nick e seus colegas usaram sua experiência para facilitar discussões no GitHub com a comunidade mais ampla de desenvolvedores que também estão lutando exatamente com esses problemas com temas de bloco.
O redesenho continua
A reformulação do WordPress.org é um empreendimento de vários anos com muitos projetos simultâneos acontecendo. Alguns dos focos de Nick e seus colegas incluem o redesenho do restante da documentação do WordPress, um segmento de conteúdo voltado para o usuário final conhecido como “HelpHub”, juntamente com os Fóruns e o Diretório de Padrões.
Ao longo do caminho, seu foco é garantir que a comunidade esteja ciente de que esses projetos de redesenho são todos públicos para análise e envolvimento.
Nick acrescentou que “Figma é público, o público do GitHub, mas é tão público quanto poderia ser do ponto de vista visual dentro da comunidade? Não. E acho que isso é algo que estamos tentando fazer melhor. Então, estamos tentando melhorar o processo para que seja mais visível no futuro.”
A equipe tem postado atualizações de forma mais proativa no blog Make WordPress, bem como em um canal dedicado do Slack, #website-redesign. O objetivo final dessas reformulações é aumentar a qualidade e o acesso à informação, mas também facilitar a contribuição para o projeto.
“Uma das coisas que realmente vimos”, disse Nick “é que uma vez que o redesenho aconteceu e houve um pouco mais de destaque nele e as pessoas começaram a usá-lo, então os problemas com a interface do usuário desapareceram e então você começar a ver problemas com o conteúdo, o que leva mais pessoas a consertar o conteúdo.”
Se você estiver interessado em contribuir para o design ou conteúdo de alguns desses próximos projetos, considere ingressar no WordPress Slack ou acompanhar o blog Make WordPress.