That would be this document.

Establish early what content you expect to require updates

At a high level, it’s important to recognize that not every piece of content can be updated across the entire site and that the method of creation greatly impacts what’s possible. As a result, it’s critical to spend time ahead of creation determining what you expect to need updates and to put that content in the appropriate format. This will make a huge difference in terms of future maintenance.

Embrace theme design at the block level

Block theme design requires a mindset shift from the previous approach of designing large sections of a theme and controlling them via updates. While a holistic view of a design is still important when creating a custom theme project, blocks require that themers approach design on a more atomic level. This means starting from the block itself, typically through theme.json customizations. The goal is that each individual “atom” (i.e., block) can be moved around, edited, deleted, and put back together without the entire design falling apart.

The more that you approach design at the block level, the less need there is to propagate updates to things like patterns and templates across the entire site. If the atomic pieces are in place, their layout should not matter.

Gee that’s rich. My particular issue right now is that I need to make some updates to a block pattern I created for my client’s site. Unfortunately, that block pattern was already in use on about 40 pages of their site, but it involves an unanticipated design issue. (As it happens, yes I probably should have thought it through a bit more before it got propagated so extensively, but the practical reality of building websites is that sometimes you don’t know what will or will not be effective at the outset — especially when you’re simultaneously dealing with end users learning how to wrangle Gutenberg — and one of the great features of the web from its inception to today is that things are easy to change later on. In fact, that has been a driving force behind template-oriented CMS platforms from the beginning. It’s the separation of functionality, design and content that has been at the heart of most well-structured website editing platforms, including WordPress, until now.

It’s easy, when you believe that what you are creating is a blogging platform, that people only use it to create blog posts that are content-heavy with mostly one-off layouts. And yes, that’s how WordPress started. But the entire team must collectively have its heads deeply inserted up Matt Mullenweg’s ass (sorry for being crass, but I’m also being honest) if they think that’s how WordPress is predominantly used, if that’s what made WordPress as big as it is. Because it’s not.

I’ve been doing “block-based” design with WordPress sites (using Advanced Custom Fields and its wonderful Flexible Content field) since well before the Gutenberg project existed. But I had a much different, less “atomic” concept of blocks. This atomic approach is great (I guess) in concept, but it is too fine-grained to be a useful tool for the average web content editor, and it makes design and development orders of magnitude more difficult and time-consuming.

I have now completed four site projects using my own custom block-based theme, and have three more underway. While there are some really “cool” features of the Block Editor (Gutenberg), these projects have also taken me much longer and been far more maddening to build, and have left my clients much less confident in their ability to easily edit their content, than anything I had done in the previous decade of working primarily with WordPress.

And this last set of three projects is in many ways a rolling back of features, because after too many months of frustration with the limitations of block themes, “version 3” of my custom theme actually reverts from using the new HTML-based page templates to using PHP-based templates. It’s a regression in a way, but I never had any intention of using the Site Editor anyway, because it’s not an easier way for me to build sites, and it grants access to elements that should be 100% hands off for the clients who’ve hired me.

And now, once again, I’ve been derailed from my work by the need to spend 45 minutes venting my frustrations over this predicament in a blog post.

So… how did I end up resolving the issue of updating the block patterns that already appear in my content? Do you really want to know? I fired up phpMyAdmin, wrote a SQL query to find all of the affected instances, and manually copy-pasted the update into them. (Yes, I could’ve written a SQL statement that would just do the replacements; I tried that first, but the replacement text was really long and was generating a MySQL error that I couldn’t quickly pin down, so it was faster to just manually edit the 40 records.)