Why would an experienced contributor say they can no longer understand Gutenberg’s code? A post from Ari, who led early work on the Font Library API, had drawn close to 87,000 views. WPwatercooler episode 482 asked me to give the background and explain what was going on.
🎙️ Episode details
- Show: WPwatercooler, episode 482, “Gutenberg It’s Complicated”
- Panel: Jason Tuckercolleague, Sé Reedcolleague, Jason Cosperacquaintance and me, Courtney Robertson
- Date: April 26, 2024
- Topics: who Ari is, finding one line of Gutenberg code, and inline documentation
- Show notes: WPwatercooler episode 482, with chapters and a transcript
🧭 Who is Ari, and what did Ari say?
First, I explained that Ari had worked at Yoast and contributed to core for years, including the Font Library. By then, Joost de Valk’s Emilia Capital sponsored Ari. I’d met Ari briefly at WordCamp Europe the year before. After about three months away from Gutenberg, Ari wrote that they couldn’t understand the code anymore and that it kept getting more complex.
🗺️ Finding the one line of Gutenberg code
In short, imagine coming back from a sabbatical. Of course, your skills are a little rusty, which is normal. But Gutenberg’s layers of dependencies and abstractions mean that even when a fix is one line, finding that line can take you through several files. Also, setting up the tools, from Node.js to npm updates, is its own hurdle.
Instead, the missing piece, I argued, was inline documentation: comments in the code that explain why something works this way and what it depends on. That’s what would have helped Ari, and it would help anyone skilled in React who is new to the codebase.
📝 Changelogs exist; inline docs in the Gutenberg code are the gap
Release notes weren’t the problem. For example, I pointed the chat to the Gutenberg 18.2 release post as an example of readable release content, the kind I used to turn changelogs into at The Events Calendar for developer customers. Instead, the gap was inside the Gutenberg code.
🧪 What can you take from this episode?
- Maintainers: write the comment that explains why, not just what, especially around abstractions.
- Returning contributors: rebuild your local setup first, and ask in the project’s channel where a feature lives.
- Companies: sponsoring documentation work keeps codebases approachable for new and returning people.
Also, more conversations like this one live in my podcast and speaking archive.
🗓️ Archival note
WPwatercooler’s episode page is dated April 26, 2024; a podcast directory lists April 29. Then I added this post on November 9, 2026, from the show notes and the publisher’s automated transcript. I quoted no one directly and reviewed the transcript, not the recording.