Saying “here’s how to write a plugin” is far too general. It gives no frame of reference for what you’re going to be covering, what the plugin is going to do, what the prerequisites are, or what the end result is going to be. It may even get a beginner’s hopes up only to let them down to leave them feel more confused by the time they’re done.

Saying “here’s how to write your first WordPress plugin” is a little bit better because it sets a level of expectation in terms of the level of experience required. If the reader is a new developer or if they are an experienced developer, it’s still going to be teaching them how to work within the confines of WordPress. Sure, there are a multiple ways to write plugins but learning how to get started is the first step towards seeing that. 

Saying “here’s how to write a plugin that will read user profile information using the WordPress API to create a unique author page” is clear. It explains exactly what it’s going to do and lays out the different points of WordPress that will be used in the tutorial. 

Even if the reader doesn’t know it yet, the author knows that, when putting something like this together, s/he is going to need to use a combination of:

  • templates or template parts,
  • the ability to read user metadata with the API,
  • safely render information from the backend to the frontend, and how to handle all of the checks in between to make sure nothing is passed up from the database to the frontend that doesn’t need to be or that’s something like an empty value.

Further, there’s an opportunity to to highlight some other best practices like sanitization, escaping, maybe internationalization, etc. All of that would be content for another article, but teasing it out can help.  And this is speaking from experience.

So why bring all of this up?

Writing Tutorials in These Gutenberg Times

First, I’m a backend engineer so the majority of the work I do at this point at my career generally revolves around PHP and anything from the application layer downward. And I enjoy that.

However, I was recently tasked with building a custom Gutenberg block for a project. Remember, I’m one of the grumpy old WordPress dudes who was around when people were writing theme tutorials before the Customizer was even a thing. By that, I mean I remember seeing tutorials for how things were generally structured.

Sure, there were places that you’d tend to steer others away from reading and other places you’d tend to steer them towards reading, and though you can’t not grow more in your career as you’ve moved forward I’ve consciously always tried to write material that I thought would be helpful and scalable at least up until a version of WordPress was released where a given API or feature was deprecated. 

Though I follow the various newsletters (like The WP Minute and The Repository and Post Status), blogs, and official sites for documentation, I couldn’t help but wonder what the proverbial tutorial landscape looked like for block development.

I know Gutenberg has been in development for five years and I know that it’s matured a lot over the course of that time. But the number of tutorials explaining how to do something that’s already outdated is absolutely incredible.

The Gutenberg Time in Which We Live

On one hand, it’s great to have such an active community of people seeking to help others and to get on board with the newest technology. But wow if things haven’t been released so quickly with so many breaking changes to have outdated tutorials (and software) so quickly. 

I know there are a lot of efforts going on to educate people on how to build software for Gutenberg and that’s great, but I do see history repeating itself a little bit in that there are sites where we want to redirect people from using and steer them towards using.

The difference, this time, is that it has more to do with the fact that the content that was written was actually good for the short time that Gutenberg was the state in which it was in at the time. 

But There are Solutions!

So, yeah, it’s a bit of a bitter pill to swallow but here we are. And thanks for various peers on Twitter, there’s a few places I recommend for review:

Case in point:

Further, I’d like to start writing tutorials like I used to write but backend stuff but for some introductory Gutenberg stuff. Again, I’m more of a backend developer but even now and again we have to come up to the surface to see what the rest of you frontenders are doing. And we should document our work, too.

As much as a bummer as it is to see such dated material in such a short time, here’s to a better future for Gutenberg tutorials.

What might that look like, though? I’m going to make an attempt in the next few days and we’ll see what happens.