10up Publishes Gutenberg Best Practices Website

10up has published a Gutenberg Best Practices website as a public resource with tutorials, documentation, and example code. Maintaining current documentation has not been a strong point of the official Gutenberg project as the pace of the project makes it difficult for contributors and extenders to keep up.

“Gutenberg introduced an entirely new editorial paradigm for content creation and page building within WordPress,” 10up Associate Director of Editorial Engineering Fabian Kaegy said. “Because the block editor is still fairly new, it is advancing quickly and changes are introduced regularly; as such, learning opportunities are scarce and we have felt an absence of best practice documentation that meets 10up standards for craftsmanship.”

10up’s Gutenberg Best Practices were written to supplement WordPress’ core documentation with what Kaegy said is a “more client-services-centric approach tailored to engineering enterprise-level editorial experiences.”

For developers who are brand new to working with the block editor, the Reference section has a wealth of information about the anatomy of a block, the fundamentals of block theming with theme.json, block extensions, block variations, and more, with supporting videos and gifs. The documentation also gives a little more context for practical usage. For example, the section about Block Transforms includes information about when and how to define block transforms.

The Training section of 10up’s Gutenberg Best Practices contains a mini crash course on the file structure of a block and all of its components, and how to build a custom block using the 10up Starter Block. This is especially helpful for developers looking for some extra guidance developing their first blocks.

The Guides section contains more advanced topics like extending core blocks and including frontend JS with a block. The documentation is available on GitHub for anyone to contribute edits. The site also links to a discussion board on GitHub where developers are welcome to join discussions and workshop the best practices in collaboration with 10up employees. 10up has published the Gutenberg Best Practices website with a beta designation and intends to update and expand it as WordPress evolves.

6

6 responses to “10up Publishes Gutenberg Best Practices Website”

  1. Kudos to the 10up team for putting this together and publishing it. When I sent it to my coworker to review he summed up the material really well: “It has a good learning journey.”

    What stands out to me over other resources about blocks is the writer explains why they consider their approach the best practice, as well as the common pitfalls you might encounter. That information is invaluable when you first start developing blocks.

    • Knowing when to use which tool is a great skill.

      And I think Docusaurus with publicly available source files is a great choice for a knowledge tool like this. Easily allow many collaborators via GitHub pull requests.

  2. I wonder if the pace has to be as fast as it is, because improvements are so critical, or if the pace could be slowed down a bit so that better documentation could be released along with updates. I am certainly grateful for 10up’s material, of course, I would be happier if it were not needed because the Gutenberg release included such documentation—sort of a “better right/complete than fast” theory.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Newsletter

Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: