Day: July 2, 2020

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.

“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, this is by no means a shot at the folks who have put the current documentation together, and I appreciate any and all work they have done so far, it’s just in serious need of a review and some refinement.”

Bossenger said in the past WordPress made it very easy for anyone with a limited amount of PHP knowledge to quickly build a plugin or theme using action and filter hooks. It was easy to look at the code and understand what it was supposed to do.

“Modern JavaScript, and specifically React, is a very different kettle of fish,” Bossenger said. “It requires a deeper level of knowledge of how React works, including new terminology and practices. Modern JavaScript can also be very confusing, especially if this is the first time you’re seeing things like arrow functions, or less verbose if statements.

“If the closest you have come to working with JavaScript in WordPress has been using jQuery, switching to React based Gutenberg development still requires some learning on your part.”

After taking two courses before he could build anything for the editor, one on React and one on Gutenberg, Bossenger said the current Block Editor handbook is not written for developers with no experience in React and modern JavaScript. He believes it needs a restructuring to better explain new concepts and fit a pattern that is easier for a newcomer to consume. He highlighted the Plugin Developer handbook as an example where the chapters follow a structure and use terminology that is more like a text book, slowly introducing the reader to new concepts.

“I would argue that it would be quite possible for someone with no plugin or PHP knowledge, armed with this handbook and Google, to build a simple plugin to meet their specific requirements quite quickly,” Bossenger said. “Currently the block editor handbook is not conducive to this.”

Bossenger is not alone in his opinion of the current documentation. Peter Tasker at Delicious Brains recently published a tutorial on creating a custom Gutenberg block. Even after working with React full-time for the past year, he found the official block editor docs to be “kind of all over the place” and difficult to parse.

After Cap commented about the lack of companies sponsoring full-time work on documentation, Bossenger tested the waters with a tweet asking if the two of them might be able to raise funds for improving Gutenberg docs.

“Just the same as Block Editor Team (and any other Make team), the Documentation Team is understaffed,” Cap said. “We can’t afford to dedicate few members to first learn and then write documentation on developing with block editor. This is the main reason for my tweet. You’ll see sponsored contributors all over core but not in documentation and I’ll dare to say that both are equally important.”

Before launching their fundraiser, Cap and Bossenger plan to go through the existing documentation, pinpoint obvious holes, and identify questions that remain unanswered for those who are new to developing for the block editor.

“Once we have a plan we can predict how much time is needed for each part,” she said. “With this plan, we will go in search for sponsors. I think there will be an option to donate even before that but nothing is certain at this point.”

Blocks are the new frontier of WordPress development. Investing in solid documentation and tutorials for beginners could have a major impact on expanding the block ecosystem. This also indirectly benefits users as they end up with a more diverse directory of blocks to choose from when customizing their WordPress sites.

Bossenger and Cap are currently working on a plan for the docs ahead of announcing their fundraiser. In the meantime, anyone who wants to contribute to improving the block creation documentation can jump in on the GitHub discussion.