Gutenberg is slowly marching towards a releasable version but has anyone tested it on a real world project? There have been a few announced but nothing significant (that I’ve seen). I’ve integrated it into a couple of themes, and mostly it’s worked well, but the process is not straightforward.
So, I was interested to read this article by Marie from Studio 24 where she showcases the process and issues she found when trying to convert a design into an editable WordPress website.
Marie found a lot of issues with Gutenberg; but the most prominent for me is that there is a lot of documentation that is either lacking in detail or out of date.
Gutenberg needs to get developers onside. Many of the projects most vocal opponents are developers, so I think they should be focusing on improving the experience for the developers who want Gutenberg to succeed.
But Gutenberg is a very different project. Not like any previous WordPress one and so what we know already is no longer useful; which means good documentation is essential.
When I started using WordPress the WordPress Codex was a lifeline. It had documentation on how to use everything and that helped me massively. There needs to be a Gutenberg equivalent. The current Gutenberg handbook is a start, but it doesn’t cover half of what is needed.
Last week I asked the team for some documentation on how to use a feature that I knew should be there, and I was pointed to a Github ticket, and given some info on Twitter, that showed me the javascript command needed.
There was no mention of what hook to enqueue the code on, or if it needed to be wrapped in some sort of document ready script. I’m reasonably competent when it comes to WordPress but the feedback was very vague. It was frustrating and reminded me of Brad Frosts article about saying Just.
They have now added a code reference for my request to the Gutenberg handbook, however it’s still just the command with no implementation details.
Of course – documentation wasn’t the only takeaway from this article. There’s issues with localization, and editor styling, and customizing the editor, and all sorts. It’s well worth checking out.
As usual we have the standard disclaimer, Gutenberg is still in development and hopefully a lot of these will be fixed, but I stand by the fact that if the documentation was more comprehensive, and kept up to date, then we would be seeing more cool things built with it. Which should mean we would be seeing more positive articles (like this glowing one on the Tavern).
Let me know what you think on Mastodon, or BlueSky (or Twitter X if you must).
Link to this page
Thanks for reading. I'd really appreciate it if you'd link to this page if you mention it in your newsletter or on your blog.