Improving WordPress Pt 4 – Where Gutenberg Lost Me (Open Letter to Core)


Gutenberg is the code name for WordPress’s new visual editor, which is designed to add block support to WordPress.  Gutenberg is not currently earmarked for a specific release, but signs seem to point toward WordPress 5.0.   It has a promising UI, and has been through a fair number of iterations already, but as work continues, I find myself more and more disenchanted with the solutions they’ve proposed.  I find myself constantly taken aback by the incredible number of flawed premises that comprise the project.

Flaw 1 – “We know our audience from, and our personal experience”

This was essentially Matt Mullenweg’s  response to the discussion of adding an opt in analytics system to, to gather usage data about the software, to inform development. Respectfully, that response is dead wrong. is a blog host, that filters out all users except those simply looking to post articles. With WordPress powering almost a quarter of the web, this is NOT as sufficient cross-section of users, and heavily biases the demographics to casual bloggers.

WordPress desperately needs data-driven development that comes from the community.  I understand that is where the money comes from, but isn’t just a side effect of the hosted blog platform, and should not be seen as a second class citizen.

A great example of this is the “kitchen sink” button that expands the advanced editor. Seven months ago, when reordering alignment buttons into the kitchen sink was a good idea, Andrew Ozz wrote a testing plugin to try to collect some data on usage. He found that in his extremely limited tests, most users expanded the kitchen sink, and left it open, to provide themselves as many options as possible. Seven months later, the new Gutenberg UI is based around hiding as many options as possible until situationally relevant. In that time, no data was collected to prove or refute the idea that users want more visibility of the tools available to them. In fact, the primary motivation of the redesign seems to be “people like Medium“. But what works for Medium may not work at all for the larger, more varied userbase of WordPress.

Flaw 2 – “We’ll build the UI, then tackle the code”

While this is a great way to get buy in very early, it means that a UI is built without regard to the underlying challenges of data management and presentation. As a result, every time a snag is hit in tying that UI to data, the kneejerk is to hack in support for the UI that people bought into, rather than adjusting to meet the actual needs of the system. We’ll see this come into conflict more when block types like columns and nesting are needed, which were completely ignored in the UI phase, and pose significant complications.

Flaw 3 – “We’ll choose a data-structure, then tackle the code”

Well, now we have the word of god down on how the data is stored, and the word of god down on how the interface looks. If it isn’t obvious, this leaves very little room for the needs of the actual code to be asserted. When one aspect of the storage method is a square peg, and one aspect of the UI is a round hole, the code needs to do both at once, leading to madness. (I am eagerly awaiting the moment when the team finally decides to tackle columns.)

Flaw 4 – “Post_content is the single source of truth”

So, WordPress has structured data needs for blocks that may be dynamic or static, and may have a large amount of meta-data attached, and it has flat output needs in various forms, such as excerpts, search fields, RSS feeds, and HTML.  It also has needs for several ways to modify the underlying structured data, in various apps, via API, or in visual editors. Clearly, the core data is structured, and should be stored as such, with all flattened views and editing interfaces being generated from that. At minimum, it could be a JSON object, or better yet, a series of database structures that could be manipulated and indexed independently.

NOPE. The team went with HTML with inserted comments.

Are you thinking WTF? well, the explanation is easy. This massive paradigm change to structured data for WordPress posts would change everything from how the API interfaces with content, to how the site renders the_content(). And that is hard. Plus, this is the #yearoftheeditor, not #yearofthedataparadigmshift, so making changes like that was written off as out of scope. They’d rather maintain a box of snakes for the next ten years, endlessly patching, then to consider a major structure change.

So, instead, we get a whole new set of problems bolted into the existing mess that is post_content. Search results will now parse through the myriad html comments in a post, as well as the shortcodes and html tags they already look at. All rendered HTML will need to be based in forms that work equally well as plain text, or auto-excerpts and feeds will look awful. Dynamic blocks will disappear, of course, so any text describing them will suddenly be orphaned in feeds and excerpts. Rendering blocks on the front end will now involve either an expensive DOM walker, to parse the WordPress comments, or an insanely complicated RegEx to parse comments, that is guaranteed to fail under certain circumstances (Regular Expressions are fundamentally not suited for parsing HTML, as HTML is not a regular language), or posts will need to be filled with opinionated HTML to support their display.

Flaw 5 – “Text editors and API editors will edit the structured data directly, while the visual editor will edit through a parsing interface”

So, the first time a text-user modifies a block in a manner that breaks an entire nested tree of blocks, they are going to scream in frustration. There is no way to recover from arbitrary changes that might break HTML, shy of including an error checking step that parses the blocks after the text version is saved, and rejects the change if it breaks things.  That way leads madness.

Structured data MUST be edited in a structured way. Trying to ignore this fact is a great way to develop yourself into a corner and build a tool that is insanely convoluted.

Flaw 6 – “We have to dance with the one we came with”

TinyMCE is an visual editor based in a content-editable block. As such, everything built in TinyMCE is inherently unstructured and buggy, and must be parsed with dom-walkers, node-parsers, and other tools that are overbuilt and inscrutable to get even half-way decent results.

The editor that was designed for Word-like operations is NOT the editor to handle structured data, and the resulting body of code is enormous.  Maintaining the Editor is going to become a herculean task, if TinyMCE is the basis.

The reason for choosing TinyMCE is familiarity, but with the number of changes necessary to implement Gutenberg, the editor won’t be familiar to anyone, so that point is moot. The secondary reason has been listed as to offer the inherent accessibility afforded by content-editable.  However, this argument is flawed too. With content-editable you get accessibility geared toward a single, typeable field. The moment you add to that, you go from having accessible features that help you, to having to fight with accessible features that are no longer relevant and often are incorrect. It is a much better idea to build your accessible interface on a solid foundation that is built to match your needs.

There are many JavaScript-based editors these days that are designed to not limit the user to the capabilities of content-editable, My money is on slate.js as the best option, but there are other contenders, such as quill.js

Flaw 7 – “There is only one visual interface for editing”

I covered this in part 3 of this series, but the idea of a single catch-all editor is deeply flawed. Pages have completely different needs from posts, which might have completely different needs for different post formats, which have completely different needs from many custom post types.  One editor for everything is not a good solution. The editor should be pluggable, and be able to be easily modified from context to context, allowing for different experiences for designers and content-editors. This sort of work is the definition of Plugin Space, and trying to hammer it all into core is only going to hurt their users.

There is a lot of talk of discontinuing support for the existing editor, in favor of the new interface. This will have a horrible effect on the literally tens of thousands of plugins, themes, and sites that make use of the editor in other contexts like settings pages and meta boxes. This is very strongly tied to flaw 1, but developing without these users in mind is foolish to the extreme.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>