Colaboradores de WordPress buscan patrocinio para mejorar los documentos para desarrolladores de Gutenberg

Los desarrolladores de WordPress, Milana Cap y Jonathan Bossenger, están iniciando una recaudación de fondos para mejorar la documentación para desarrolladores de Gutenberg. La conversación comenzó ayer cuando Cap tuiteó sobre cómo a menudo se pasa por alto la documentación cuando las empresas contratan colaboradores de tiempo completo para trabajar en WordPress.

“Cuando su comunidad no puede aprender su software, entonces no tiene colaboradores”, dijo Cap. “La documentación y los tutoriales son mucho más importantes para los proyectos de software de código abierto de lo que la gente cree”.

La primera vez que Cap comenzó a solicitar documentación de Gutenberg fue en la Cumbre de la comunidad en París en 2017. Ha estado tratando de llamar la atención de la comunidad desde entonces.

“Hay muchos agujeros en la documentación del editor de bloques para desarrolladores, pero el más obvio es cómo empezar”, dijo Cap. “El comienzo de la documentación para desarrolladores no dice nada sobre cómo comenzar. “Solo dice lo que puedes hacer con un bloque pero no _cómo_. Los desarrolladores júnior, los desarrolladores exclusivos de PHP y cualquier persona a la que se refiera la documentación, no saben cómo se ve el código de un bloque, dónde colocarlo, cómo incluirlo, etc., y mucho menos cómo crear un bloque personalizado con componentes personalizados y ajustes."

Parte del desafío de documentar el editor de bloques es que está en desarrollo activo. Las mejoras y los refinamientos se envían constantemente al complemento de Gutenberg y no siempre es fácil hacer un seguimiento de lo que está o no está disponible actualmente en el núcleo. Dado que WordPress está introduciendo de forma inminente la búsqueda de directorios de bloques, es un buen momento para formalizar la documentación de creación de bloques.

“Los ejemplos de código faltan alarmantemente en todos los documentos”, dijo Cap. “Existen los ejemplos más básicos, pero falta cómo construir realmente algo utilizable. Entonces, en esta primera página, se nos envía a un tutorial, pero ese tutorial no está optimizado para personas que nunca antes han construido un bloque. Siguiéndolo, he fallado y fallaré en construir el bloque”.

Marcus Kazmierczak y un equipo de colaboradores de documentación están intentando reconstruir el tutorial en el manual oficial del editor de bloques. Un problema de GitHub centrado en abordar las lagunas en la documentación actual del desarrollador alberga un debate activo sobre la mejor manera de reescribir los documentos para las personas que son nuevas para bloquear el desarrollo.

“Este es un muy buen comienzo, pero aún queda mucho trabajo por hacer”, dijo Cap. “La documentación completa está escrita por personas que conocen y entienden React y Gutenberg pero están 'malditos con el conocimiento'. No tienen mucho tiempo para dedicarlo a comprender cuánto no saben los demás y con qué detalle se debe escribir la documentación. Para ser honesto, no creo que deban gastar su tiempo en eso. Tenemos un equipo de documentación y estamos dispuestos a participar, pero es necesario algún tipo de puente”.

El problema con la documentación del desarrollador de Gutenberg: no es amigable para los recién llegados

“El 'problema' tal como lo veo con la documentación del editor de bloques es que, a diferencia de otra documentación de WordPress, está escrita para desarrolladores de JavaScript experimentados y no está dirigida a principiantes”, dijo Bossenger. “También debo señalar que esto de ninguna manera es una oportunidad para las personas que han reunido la documentación actual, y aprecio todo el trabajo que han realizado hasta ahora, solo necesita una revisión y un refinamiento. ”

Bossenger dijo en el pasado que WordPress hizo que fuera muy fácil para cualquier persona con una cantidad limitada de conocimientos de PHP crear rápidamente un complemento o tema utilizando ganchos de acción y filtro. Era fácil mirar el código y entender lo que se suponía que debía hacer.

“JavaScript moderno, y específicamente React, es un caldero de pescado muy diferente”, dijo Bossenger. “Requiere un nivel más profundo de conocimiento sobre cómo funciona React, incluidas nuevas terminologías y prácticas. El JavaScript moderno también puede ser muy confuso, especialmente si es la primera vez que ve cosas como funciones de flecha o declaraciones if menos detalladas.

“Si lo más cerca que has estado de trabajar con JavaScript en WordPress ha sido usando jQuery, cambiar al desarrollo de Gutenberg basado en React aún requiere algo de aprendizaje de tu parte”.

Después de tomar dos cursos antes de poder crear algo para el editor, uno en React y otro en Gutenberg, Bossenger dijo que el manual actual del Editor de bloques no está escrito para desarrolladores sin experiencia en React y JavaScript moderno. Él cree que necesita una reestructuración para explicar mejor los nuevos conceptos y adaptarse a un patrón que sea más fácil de consumir para un recién llegado. Destacó el manual del desarrollador de complementos como un ejemplo donde los capítulos siguen una estructura y usan una terminología que se parece más a un libro de texto, introduciendo lentamente al lector a nuevos conceptos.

“Yo diría que sería muy posible que alguien sin conocimientos de PHP o complementos, armado con este manual y Google, cree un complemento simple para cumplir con sus requisitos específicos con bastante rapidez”, dijo Bossenger. "Actualmente, el manual del editor de bloques no es propicio para esto".

Bossenger no está solo en su opinión sobre la documentación actual. Peter Tasker de Delicious Brains publicó recientemente un tutorial sobre la creación de un bloque de Gutenberg personalizado. Incluso después de trabajar con React a tiempo completo durante el último año, descubrió que los documentos oficiales del editor de bloques estaban "por todos lados" y eran difíciles de analizar.

Después de que Cap comentara sobre la falta de empresas que patrocinen el trabajo a tiempo completo en documentación, Bossenger probó las aguas con un tweet preguntando si los dos podrían recaudar fondos para mejorar los documentos de Gutenberg.

“Al igual que el equipo de edición de bloques (y cualquier otro equipo de Make), el equipo de documentación no tiene suficiente personal”, dijo Cap. “No podemos darnos el lujo de dedicar pocos miembros a aprender primero y luego escribir documentación sobre el desarrollo con el editor de bloques. Esta es la razón principal de mi tweet. Verá colaboradores patrocinados en todo el núcleo, pero no en la documentación, y me atrevería a decir que ambos son igualmente importantes”.

Antes de lanzar su recaudación de fondos, Cap y Bossenger planean revisar la documentación existente, identificar los agujeros obvios e identificar las preguntas que quedan sin respuesta para aquellos que son nuevos en el desarrollo del editor de bloques.

“Una vez que tenemos un plan, podemos predecir cuánto tiempo se necesita para cada parte”, dijo. “Con este plan iremos en busca de patrocinadores. Creo que habrá una opción para donar incluso antes de eso, pero nada es seguro en este momento”.

Los bloques son la nueva frontera del desarrollo de WordPress. Invertir en documentación sólida y tutoriales para principiantes podría tener un gran impacto en la expansión del ecosistema de bloques. Esto también beneficia indirectamente a los usuarios, ya que terminan con un directorio de bloques más diverso para elegir al personalizar sus sitios de WordPress.

Bossenger y Cap están trabajando actualmente en un plan para los documentos antes de anunciar su recaudación de fondos. Mientras tanto, cualquier persona que quiera contribuir a mejorar la documentación de creación de bloques puede participar en la discusión de GitHub.