WordPress Contributors Seek Sponsorship for Improving Gutenberg Developer Docs

WordPress Contributors Seek Sponsorship for Improving Gutenberg Developer Docs

WordPress developers Milana Cap and Jonathan Bossenger are starting a fundraiser for improving Gutenberg developer documentation. The conversation began yesterday when Cap tweeted about how documentation is often overlooked when companies hire full-time contributors to work on WordPress. I wish someone pay people to work on Gutenberg Docs. All devs who understand Gutenberg are working on building it and no one has the time to document it. On the other hand, Gutenberg and React are so foreign to WordPress PHP devs that no one is being able to learn it. https://t.co/iFmpd24TwH — Milana Cap (@DjevaLoperka) June 30, 2020 “When your community is unable to learn your software then you have no contributors,” Cap said. “Documentation and tutorials are far more important for Open Source Software projects than people realize.” The first time Cap began asking for Gutenberg documentation was at the Community Summit in Paris, 2017. She has been trying to direct the community’s attention to it since then. “There are many holes in block editor documentation for developers but the most obvious one is how to start,” Cap said. “The beginning of documentation for developers doesn’t say anything about getting started. “It says only what you can do with a block but not _how_. Junior developers, PHP-only developers and anyone for whom is that documentation meant, doesn’t know how a block’s code looks, where to put it, how to include it, etc, let alone how to build a custom block with custom components and settings.” Part of the challenge of documenting the block editor is that it is under active development. Enhancements and refinements are constantly pushed out to the Gutenberg plugin and keeping track of what is or is not currently available in core is not always easy. As WordPress is imminently introducing block directory search, it is a good time to formalize block creation documentation. “Code examples are alarmingly missing all over docs,” Cap said. “The most basic examples exist but how to actually build something usable is missing. So, on this first page we are sent to a tutorial but that tutorial is not optimized for people who have never built a block before. Following it, I have and will fail to build the block.” Marcus Kazmierczak and a team of documentation contributors are attempting to rebuild the tutorial in the official block editor handbook. A GitHub issue focused on addressing gaps in the current developer documentation is home to an active discussion about the best way to rewrite the docs for people who are new to block development. “This is a very good start but there’s still a lot of work to be done,” Cap said. “Complete documentation is written by people who know and understand React and Gutenberg but are ‘cursed with knowledge.’ They don’t have much time to spend on understanding just how much others don’t know and in what detail documentation should be written. To be honest, I don’t think they should spend their time on that. We have a Documentation Team and we are willing to jump in but some sort of bridge is necessary.” The Problem with Gutenberg Developer Documentation: It’s Not Friendly for Newcomers “The ‘problem’ as I see it with the block editor documentation is that, unlike other WordPress documentation, it is written for experienced JavaScript developers, and not aimed at beginners,” Bossenger said. “I should also point out,  » Read More

Like to keep reading?

This article first appeared on wptavern.com. If you'd like to keep reading, follow the white rabbit.

View Full Article

Leave a Reply