Les contributeurs WordPress recherchent un parrainage pour améliorer la documentation des développeurs de Gutenberg

Les développeurs WordPress Milana Cap et Jonathan Bossenger lancent une collecte de fonds pour améliorer la documentation des développeurs de Gutenberg. La conversation a commencé hier lorsque Cap a tweeté sur la façon dont la documentation est souvent négligée lorsque les entreprises embauchent des contributeurs à plein temps pour travailler sur WordPress.

"Lorsque votre communauté est incapable d'apprendre votre logiciel, vous n'avez aucun contributeur", a déclaré Cap. "La documentation et les didacticiels sont bien plus importants pour les projets de logiciels open source que les gens ne le pensent."

La première fois que Cap a commencé à demander de la documentation sur Gutenberg, c'était lors du Sommet de la communauté à Paris en 2017. Depuis lors, elle essaie d'attirer l'attention de la communauté sur ce sujet.

"Il existe de nombreux trous dans la documentation de l'éditeur de blocs pour les développeurs, mais le plus évident est de savoir comment commencer", a déclaré Cap. « Le début de la documentation pour les développeurs ne dit rien sur la prise en main. "Il dit seulement ce que vous pouvez faire avec un bloc mais pas _comment_. Les développeurs juniors, les développeurs PHP uniquement et toute personne à qui cette documentation est destinée ne savent pas à quoi ressemble le code d'un bloc, où le mettre, comment l'inclure, etc., et encore moins comment créer un bloc personnalisé avec des composants personnalisés et réglages."

Une partie du défi de documenter l'éditeur de blocs est qu'il est en cours de développement actif. Des améliorations et des améliorations sont constamment apportées au plugin Gutenberg et il n'est pas toujours facile de garder une trace de ce qui est ou n'est pas actuellement disponible dans le noyau. Comme WordPress introduit de manière imminente la recherche de répertoires de blocs, c'est le bon moment pour formaliser la documentation de création de blocs.

"Les exemples de code manquent de manière alarmante dans tous les documents", a déclaré Cap. « Les exemples les plus élémentaires existent, mais il manque la manière de construire quelque chose d'utilisable. Ainsi, sur cette première page, nous sommes dirigés vers un didacticiel, mais ce didacticiel n'est pas optimisé pour les personnes qui n'ont jamais construit de bloc auparavant. Après cela, j'ai et je ne parviendrai pas à construire le bloc.

Marcus Kazmierczak et une équipe de contributeurs à la documentation tentent de reconstruire le didacticiel dans le manuel officiel de l'éditeur de blocs. Un problème GitHub axé sur la résolution des lacunes dans la documentation actuelle des développeurs abrite une discussion active sur la meilleure façon de réécrire les documents pour les personnes qui découvrent le développement de blocs.

"C'est un très bon début, mais il reste encore beaucoup de travail à faire", a déclaré Cap. "La documentation complète est rédigée par des personnes qui connaissent et comprennent React et Gutenberg mais qui sont" maudites par la connaissance ". Ils n'ont pas beaucoup de temps à consacrer à comprendre à quel point les autres ne savent pas et dans quel détail la documentation doit être écrite. Pour être honnête, je ne pense pas qu'ils devraient passer leur temps là-dessus. Nous avons une équipe de documentation et nous sommes prêts à intervenir, mais une sorte de passerelle est nécessaire. »

Le problème avec la documentation du développeur Gutenberg : elle n'est pas conviviale pour les nouveaux arrivants

"Le" problème "tel que je le vois avec la documentation de l'éditeur de blocs est que, contrairement à d'autres documentations WordPress, il est écrit pour les développeurs JavaScript expérimentés et ne s'adresse pas aux débutants", a déclaré Bossenger. "Je dois également souligner que ce n'est en aucun cas un coup de feu pour les personnes qui ont rassemblé la documentation actuelle, et j'apprécie tout le travail qu'ils ont fait jusqu'à présent, c'est juste un sérieux besoin d'un examen et de quelques raffinements. ”

Bossenger a déclaré que dans le passé, WordPress permettait à toute personne ayant une connaissance limitée de PHP de créer rapidement un plugin ou un thème à l'aide de crochets d'action et de filtre. Il était facile de regarder le code et de comprendre ce qu'il était censé faire.

"Le JavaScript moderne, et plus particulièrement React, est une paire de manches très différente", a déclaré Bossenger. «Cela nécessite un niveau de connaissance plus approfondi du fonctionnement de React, y compris une nouvelle terminologie et de nouvelles pratiques. Le JavaScript moderne peut également être très déroutant, surtout si c'est la première fois que vous voyez des choses comme des fonctions fléchées, ou des instructions if moins détaillées.

"Si le plus proche de travailler avec JavaScript dans WordPress a été d'utiliser jQuery, le passage au développement Gutenberg basé sur React nécessite encore un certain apprentissage de votre part."

Après avoir suivi deux cours avant de pouvoir créer quoi que ce soit pour l'éditeur, un sur React et un sur Gutenberg, Bossenger a déclaré que le manuel actuel de l'éditeur de blocs n'était pas écrit pour les développeurs sans expérience en React et en JavaScript moderne. Il pense qu'il a besoin d'une restructuration pour mieux expliquer les nouveaux concepts et s'adapter à un modèle plus facile à consommer pour un nouveau venu. Il a souligné le manuel du développeur de plugins comme exemple où les chapitres suivent une structure et utilisent une terminologie qui ressemble plus à un manuel, introduisant lentement le lecteur à de nouveaux concepts.

"Je dirais qu'il serait tout à fait possible pour quelqu'un sans plugin ou connaissance de PHP, armé de ce manuel et de Google, de créer un plugin simple pour répondre assez rapidement à ses besoins spécifiques", a déclaré Bossenger. "Actuellement, le manuel de l'éditeur de blocs n'est pas propice à cela."

Bossenger n'est pas le seul à avoir un avis sur la documentation actuelle. Peter Tasker de Delicious Brains a récemment publié un tutoriel sur la création d'un bloc Gutenberg personnalisé. Même après avoir travaillé avec React à plein temps au cours de l'année écoulée, il a trouvé que les documents officiels de l'éditeur de blocs étaient "un peu partout" et difficiles à analyser.

Après que Cap ait commenté le manque d'entreprises parrainant un travail à plein temps sur la documentation, Bossenger a testé les eaux avec un tweet demandant si les deux pourraient être en mesure de collecter des fonds pour améliorer les documents de Gutenberg.

"Tout comme l'équipe de l'éditeur de blocs (et toute autre équipe Make), l'équipe de documentation est en sous-effectif", a déclaré Cap. « Nous ne pouvons pas nous permettre de consacrer quelques membres à apprendre d'abord puis à écrire de la documentation sur le développement avec l'éditeur de blocs. C'est la principale raison de mon tweet. Vous verrez des contributeurs sponsorisés partout dans le noyau mais pas dans la documentation et j'oserai dire que les deux sont tout aussi importants.

Avant de lancer leur collecte de fonds, Cap et Bossenger prévoient de parcourir la documentation existante, d'identifier les lacunes évidentes et d'identifier les questions qui restent sans réponse pour ceux qui débutent dans le développement pour l'éditeur de blocs.

"Une fois que nous avons un plan, nous pouvons prédire combien de temps il faudra pour chaque partie", a-t-elle déclaré. «Avec ce plan, nous allons partir à la recherche de sponsors. Je pense qu'il y aura une option pour faire un don même avant cela, mais rien n'est certain à ce stade.

Les blocs sont la nouvelle frontière du développement WordPress. Investir dans une documentation solide et des didacticiels pour les débutants pourrait avoir un impact majeur sur l'expansion de l'écosystème de blocs. Cela profite également indirectement aux utilisateurs car ils se retrouvent avec un répertoire plus diversifié de blocs parmi lesquels choisir lors de la personnalisation de leurs sites WordPress.

Bossenger et Cap travaillent actuellement sur un plan pour les docs avant d'annoncer leur collecte de fonds. En attendant, toute personne souhaitant contribuer à l'amélioration de la documentation sur la création de blocs peut participer à la discussion GitHub.