So a funny thing happened to me on my way to learning Gutenberg. You know, Gutenberg! That thing in WordPress that has 1/3 of the internet building bomb shelters and writing flaming angst-filled rants on Github? I finally dug into it, futzing with the repo and the documentation—and the thing, is, I sorta dig it.

Okay, I sorta-really dig it.

Anyway, I started taking tutorials on Gutenberg plugins to get my head wrapped around it and kept running into this issue where the authors either assumed:

  • You knew about it. So they wrote short articles focused on one small piece of functionality; or…
  • You knew nothing. So they started from scratch teaching you about everything to do with JS.

The quality wasn’t all that great, either. I don’t want to bust on anyone because I honestly appreciate their hard work, but there were some articles that went on for pages that never really got anywhere.

Anyone who’s been in WordPress development for any length of time knows that the truth is always in the source—and the source is beautiful! However, the documentation within the source is a little confusing. I can only speculate that it’s written from a perspective of a developer looking to integrate Gutenberg in to their product rather than a WordPress plugin developer looking to use Gutenberg features.

How do you learn GB?

Once I got my head mostly around the changes I ran into a problem: How could I expect my developers to get into this?

See, not everyone is great at teasing out how to use features from source. It’s not a crime. We were all junior once. They needed tutorials—hell, I need tutorials if I want to learn something quickly.

I wrote a quick plugin. Nothing fancy, just some bits that I thought were useful and interesting. Then I started writing up some readme.md files to document some of the weirder things I’d done.

When the docs weren’t enough, I thought “Hey, I’ll put this on my blog so I can just link them to it.” The readme files got even more beefy on content and started looking more like learning. Huh.

Non-Trivial Gutenberg

It was at this point I got serious about it: If my developers could use a tutorial on building a Gutenberg plugin from scratch, maybe others could as well.

Non-Trivial Gutenberg is a Github repo I created that contains the plugin itself in the master branch. However, each of the other branches represents a ‘step’ in the process of building the plugin, including all the instruction it took to get there in the readme.

The project itself is a plugin to reproduce the functionality found on the ChefSteps recipes where they have the full ingredients list along with some details about cooking and prep time, equipment, etc. Then they have each step of the recipe that has just the ingredients for that step.

Being WordPress, I wanted to make it a bit more challenging (and useful) by having the user populate the steps, and the summary update automatically.

In addition, I wanted to create controls that would allow viewers of the recipe to alter the yield and units for the entire recipe in one go.

These features aren’t simple; They’re ‘non-trivial’ and the course (because it stopped being an article or small tutorial) is the same.

Let’s call it “alpha”

I’ve written 3 “chapters” so far and am having far too much fun. The tone is fairly snarky and self-deprecating. When I started writing it I’d been reading Charles Stross’ The Laundry Files, so the writing is a bit on the BOFH side of technical silliness.

The content is a bit rough right now: Some of the snark goes a bit further than I want while some sections just aren’t very funny. I started thinking I’d avoid explaining ES6/Next but found some things needed explaining and have backed off of that a bit.

Once I get the initial draft ready, I’ll probably bug some people for feedback (if you’re up for that, please let me know on the repo). Once that’s done, I may try to convert it from a collection of readme files to some easier to consume Github pages with better code and image examples.

Hell, if someone wants to pay me to make videos, I’m down with that too.

At the end of the day, I’m having fun writing it. I hope someone gets something out of it too.