También escribo en Español

Gutenberg, or the Ship of Theseus

How can a system fundamentally evolve without drastically changing? WordPress can build incredible sites, yet the usability and clarity that used to be a driving force for its adoption has been fading away. The present reality is that many people struggle using WordPress as a tool for expression—they struggle to compose richer posts with media, to get their site looking the way they want, to imitate how a theme demo looks, or to set up and customize a store. There is a disconnect between what is edited in a given field somewhere in the interface with how it will look on the real site. WordPress has always been about the user experience, and that needs to continue to evolve under newer demands. Gutenberg is an attempt at fundamentally addressing those needs, based on the idea of content blocks. It’s an attempt to improve how users interact with their content in a fundamentally visual way, while at the same time giving developers the tools to create more fulfilling experiences for the people they are helping.

How can such a vision happen without dismantling, rebuilding, fragmenting, or breaking the WordPress ship that for over a decade has been carrying the thoughts, joys, and livelihoods of millions of people and more than a quarter of the web?

The ship, like Theseus’, needs to continue sailing while we upgrade the materials that make it. It needs to adapt to welcome new people, those that find it too rough to climb on board, too slippery a surface, too unwelcoming a sight, while retaining its essence of liberty. This is not an easy challenge—not in the slightest. Indeed, we called it Gutenberg for a reason, for both its challenges and opportunities, for what it can represent in terms of continuity and change. It is an ambitious project and it needs the whole WordPress community to succeed. I’d like to start examining some of the decisions made along the way, and the ones that are still to come.

Optimize for the user. An early overview for the project described some of the requirements it faced from a document and data structure perspective. Namely, how can we introduce the notion of content blocks in a way that is transparent to the existing ecosystem while allowing us to rapidly iterate on what ultimately matters the most—the user experience. This means being able to start using Gutenberg very early on without losing access to your content (opening it in other editors, for instance) and without changing how rendering the document works. The overall principle has been to let the machines do what they are good at. I won’t go into much detail here on the specific technical details because we have written about it in the project documentation and other blog posts. Honoring the user content as HTML is important: it assures their posts remain in a highly accessible way for the future and avoids platform lock-in.

On Guides and Placeholders. It is true that WordPress is capable of creating sophisticated sites and layouts. The issue is you need to know how to do it. And getting there requires a level of commitment and expertise that should be unnecessary. Why do users have to bear the weight of convoluted setups to work around the lack of a solid and intuitive visual experience?

This question is what brought us to the concept of blocks in the first place. The simplified nature of blocks, which optimizes for the direct manipulation of content and a single way to insert it, proposes an evolution of the WordPress model. It also comes with interesting opportunities. For example: how many themes have remarkable presentation in their demo sites but require Herculean efforts to replicate? A core ingredient of blocks is that, by their nature, they have a defined “empty state” that works as a placeholder describing how someone can interact with it. Blocks can guide a user as they craft their content intuitively. They are contextual tutorials that both show and teach how to add content. Here is an example of an image block that has no content:


On Templates. Imagine defining a whole page template as a set of default blocks, ready to be filled once the user creates a page; or a custom post type that specifies only certain blocks as available and has them already present in the page instead of a blank canvas. Imagine a simple site meant for publishing pictures where the default block can be just an image block, streamlining the process of creating content in the context of its purpose. On mobile this could reduce the time spent setting things up. This flexibility replaces one of the main needs for post formats, a long quest to allow more diversity of expression. That is, a UI that is contextual to the type of content being created. It also scales further into more advanced post types. A “book” block can include several distinct fields within the context of exactly how it will be presented. A business running an ecommerce plugin can set up pages with products and related blocks—while the users just have to fill in the fields. Finally, themes could now guide their users to the satisfaction of achieving the desired look, without ever leaving the composing interface.

A Powerful Design Tool. This is an important idea to clarify. Contrary to a worried perception that designs will be susceptible to breaking if the user can edit things, Gutenberg aims to give developers a way to define and protect structural markup and their design while giving users the ability to directly edit the information intuitively. Rather than making it easy to mess up a design by mistake or lack of knowledge, Gutenberg protects the design and guides the user. What used to require a mixture of widgets, opaque shortcodes, different meta-boxes, and an instruction sheet to follow—all without a direct visual indication of how things would end up looking—can now be done within a block that looks like the final result. The designer is able to create sophisticated layouts that users can interact with easily and directly without the fear of breaking things.

This puts more tools in the hands of developers and designers without alienating users. The benefit of direct manipulation is that there is no cognitive barrier to overcome—what you see is what you edit. Blocks can define what is editable and in which ways. Their markup cannot be ruined because the block is explicit about how the information will be presented. What used to require a complex set of abstractions can now become a simple structural block that is easy to edit, yet hard to break.

Themes can also provide styles for individual blocks, which can, in aggregation, fundamentally alter the visual appearance of the whole site. You can imagine themes becoming more about the presentation of blocks, while the functional parts can be extracted into blocks (which can potentially work across multiple theme variations). Themes can also provide templates for multiple kind of pages—colophon, products, portfolios, etc., by mixing blocks, setting them up as placeholders, and customizing their appearance.


Discovering Blocks. One of the goals of the block editor is to consolidate the different ways content can be created under the same interface pattern. This not only surfaces a lot of “hidden” features of WordPress but also opens new opportunities for the entire plugin ecosystem. Once the way a user creates content goes through a predictable interface flow, WordPress can surface optional plugins in the right context. If a user searches in the block inserter for something they want to add to their site, and a block doesn’t currently exist, we can immediately search for relevant plugins that might offer such blocks:


On the Layers of the Onion. In order to shift the content creation paradigm without breaking expectations, there are several layers of architecture working in tandem. There is a lot going on before Gutenberg finally outputs a block to the post. First, we get the raw content of the post; we then identify blocks through a grammar parser; we allocate additional attributes for a block based on different heuristics; we build a tree of block objects; we attempt to validate that the shape the block wants to output matches what we have; we finally pass the block type to a visual component which renders the edit context the block has specified when it was registered. All of this happens fast. Yet the different stages and isolated steps grants us a lot of possibilities. If you have already tested the Gutenberg plugin you might have seen a dialog like the following:


This occurs during the “validate what the block can save matches what we have” step. Gutenberg starts with a very strict baseline to allow us to iterate and build the layers we need for an optimal experience. This means if the markup for a paragraph block is lacking p tags, we can identify that as an error. There are three ways we currently offer to resolve it: let the block force what it expects overwriting extraneous markup; convert a block to “classic mode” which switches the block type to be handled by the classic WordPress editor (within Gutenberg); and transforming the block into an HTML block where you can write whatever markup is desired. This is a powerful mechanism and there’s a lot we can do with it. In future releases we’d want to display a before & after comparison for blocks where we detect changes above a certain threshold. Furthermore, these operations are isolated to the block, which gives a lot of granularity to further refine the experience with additional context.

Handling Multiple Sources. In addition to being able to validate blocks, we can also transform generic content into Gutenberg blocks. We are exploring these behaviours through the ability to paste arbitrary content into the editor. (Gutenberg optimizes pasting for several sources, like Google Docs, Microsoft Office, Apple Pages, older WordPress posts, and general web content). It also supports pasting plain text markdown and converting it to blocks. Since blocks are isolated, it is possible to mix different content types without risking the integrity of other blocks.


Markdown can often be great for writing, but it’s not necessarily the best environment for working with rich media and embeds. With the granularity afforded by blocks you could intermix markdown blocks with any other block, adapting to whatever is the most convenient way to express a specific kind of content. Whenever a block cannot be interpreted, we can also handle it as a plain HTML block. In future releases, you’d be able to edit individual blocks as HTML without having to switch the entire editor mode. Individual HTML blocks can also be previewed in place and immediately.

On Granularity. With the abstraction blocks provide, we can also build several tools that take advantage of the fact the full document is broken down into smaller units with semantic value. An example could be the document outline functionality that leverages the presence of heading blocks and allows the user to navigate through the document easily. It can also warn if it detects incorrect heading levels in the outline. Other plugins, like Yoast, could more surgically tailor their tools on a much smaller surface by focusing on single blocks at a time instead of having to deal with the entire document. This same granularity is allowing us to develop a collaborative editing framework where we can lock content being edited by a peer on per block basis, instead of having to lock down the whole post.

A Powerful Developer Tool. Gutenberg not only comes with several user-facing blocks, but the tools we use to create them and power their functionality are also available as components for others to build their own blocks. Our hope is that creating new blocks can be as easy as combining some of our tools, defining new markup and its presentation. This sharing of tools also ensures the user experience is more consistent. We might even look at building a “block composer” (block editor, if you will!) in the future where you can create custom blocks and package them for release. By reusing these pieces, the developer benefits from all the work that went behind them, including things like built in accessibility. These components can also take cues from themes— like the color palette component does—allowing the theme to overwrite the default colors.


Looking Beyond the Post. Gutenberg is initially focused on the post editor but the overarching plan is that it becomes the basis for general editing and customization in WordPress. There are features already in progress that expand beyond the content of the post. “Global Blocks” will allow a user to reuse a specific block (with its content) through multiple posts or pages. This absorbs some of the simpler needs that custom post types historically covered: a “testimonial” can become a simple Quote block that is now globally saved and accessible across all posts through the block inserter. Blocks are also able to save attributes in meta fields, if needed, granting continuity to existing features. Overall, the concept of the block is not about where it stores data, but how the user interacts with it. Blocks will also support nesting, opening further possibilities for customization.

Once Gutenberg is capable of handling all the pieces that visually compose a site—with themes providing styles for all the blocks—we end up with an editor that looks exactly like the front-end. (And at that point, we might just call it front-end editing.) Yet we’d had arrived at it through gradually improving the pieces of our familiar ship, in a way that didn’t cause it to collapse or alienated the people aboard. We want to accomplish this in a way that would allow us to refine and correct as we iterate and experience the reality of what is being built and how it is being used.

Gutenberg is about converting the need for discrete data from one of indirect manipulation into a direct and richer visual experience. It doesn’t seek to remove existing functionality—shortcodes still work the same way—but introduce new ways of interacting with the content. It is an attempt at improving how users can connect with their site in a visual way, not at removing the flexibility and power that has made WordPress thrive. There might be a time when the old ways become obsolete and disappear, absorbed by the richer and clearer interface of blocks, but we are doing as much as possible to make this a process. The old doesn’t have to disappear suddenly, it can be gradually shaped into the new.

Thank you to Mark Armstrong for his feedback and suggestions.

Abstractions and the burden of knowledge

When should abstractions be made in a codebase? Since open-sourcing Calypso I’ve spoken on a few occasions about how abstractions lead to burdens of knowledge, and how we need to be careful about the kind of concepts we create. In the development values for the project we write: “we know that no abstractions are better than bad abstractions”. Why is this an important value? In a post a couple weeks ago, Lance Willett asked me to follow up on what that implies and the kind of impact it can have for learning a project.

From a philosophical point of view, abstractions are concepts we put in place to interpret events, to think about reality through a certain formality instead of dealing with the inherent plurality of reality itself. They represent ideas and act as prejudgements for the shape of our perception. In this regard, they cannot, by definition, stand to the scrutiny of reality. They mediate our understanding by existing between reality and our representation of it. They are the razors with which we try to make the vastness of reality somehow apprehensible; yet inherently false as they attempt to reduce and formulate what is vast and different under principles and categories.

In the world of development, abstractions are essentially a way of organising complexity. The problem is that complexity rarely vanishes. Instead, it remains hidden under those layers of meaning, shielded by of our abstractions. The simplification it seeks to bring usually ends up adding complexity on top of existing complexity.

When carefully chosen they can augment the understanding of how things work by teaching the underlying complexity accurately, but they do generally come at a cost. They come at the expense of adding to the pile of things you need to know to operate within the codebase. By absorbing structural complexity they gradually take the place of what needs to be learned. Very often, given our propensity to create early (and misguided) abstractions, they solidify practices and force certain meanings that sometimes are best kept loose.

That is where being aware of the kind of abstractions you are forcing people to learn becomes important in a common project. Abstractions, at their best, manage the increasing complexity of any system, and may be worth the tradeoff in certain situations. But, at their worst, they add a new layer of cognitive burden you need to cope with, distorting what is actually going on, and imposing the wrong kind of conceptual hierarchy or sameness among entities. Names and groups, for example, come at the cost of having to decide where something belongs to. Does a fall under P or Q? Should we create R for these things that are partially PQ at the same time? Is our decision of having Ps and Qs forcing us to only create Ps and Qs?

One fresh example that comes to mind for me on this tradeoff is a small abstraction we created in Calypso to manage application state, called createReducer. It’s intention is well meant — simplify the boilerplate and the interface with which to handle the serialization of pieces of the state tree so developers can move faster — yet by taking a conceptual higher ground they sometimes convey more than what it was meant to achieve. People looking through the codebase would see it as the semantic way in which they ought to create any new reducer; since the interface appears simple enough, they would default to using it. Was that the intention? Perhaps. But now something that could have been a simpler reducer inherits a complex behaviour by using a utility that appears simple.

How do you overcome these situations? Naming things properly is of course important, yet no name is strictly perfect; education and documentation do help, but understanding what you are reinforcing at a design level may be even more important, since abstractions are always teaching patterns. Which comes back to the first idea; abstractions naturally become burdens of knowledge and you need to decide when and where you are willing to take their price.

The Kuleshov Effect

Andrei Tarkovsky once defined cinema as sculpting in time. The most distinct feature of web design, as it is compared to other forms of design, is precisely that it exists in time. If graphic design was often thought as the corollary of painting, then web and interaction design could very well be the corollary of filmmaking. As such, it seems to be in it’s infancy when it comes to the lessons discovered by cinema through its short centennial history.

During the early 20th century, film creators realized editing and montage were core aspects of the craft, so redefining that many held it as the one distinct essence of cinema. The one thing that moved it from a mere technical advance in photography and motion study, to an art form capable of wonders. One of these concepts was a particular study known as the Kuleshov effect, demonstrated by Lev Kuleshov, a Russian filmmaker of the golden era of montage exploration.

The experiment was quite simple, but with profound consequences. He chose a fragment of a close-up shot of a soviet actor staring, one in which the acting was particularly neutral. He then juxtaposed that fragment with other pieces of film — in particular, one of a plate of food, another one of a dead girl in a coffin, and another one of a child playing.

He showed this sequence, put together, to an audience — and the reactions were remarkable. The people specially lauded the acting, where the actor could so profoundly represent hunger (looking at the food), sorrow (looking at the dead woman), and nostalgia (looking at the child playing). The aesthetic consequences of this realization are captivating, and extremely vigorous. 1

This was the same exact shot of the actor doing nothing in particular, eminently not-acting. However, and as with most true art forms, aesthetic representation is synthetic. The viewer fills the gaps, connects the pieces, and infers more than what is the plain material. Particularly, knowledge, concepts, and experiences are being derived, created in that empty gap where two fragments connect. There was no “hunger” implicit in the acting (it wasn’t even the intention of the actor) nor in the food itself. The sentiment of hunger exists only in the evolving of time created by the assembling of these two fragments. 2

This, of course, has gigantic impacts on cinema, and good directors know how to work with this to achieve sublime beauty that goes beyond what seems to be represented on each screen fragment. It also matters greatly to actors, obviously, because their performance is not just what they intend to act, but how their shots are pieced together; what they look at, and what comes before and after. Good actors also know this.

And now, back to the field of interaction design, how does this affect those who practice it? I believe this has significant consequences here all the same. Largely unexplored. There’s a distinctive lack of thought around this in-between area where connections are created, emerging into something that cannot be reduced to the parts. What happens when someone goes from one page to the other? What happens in the switch of context? Do web designers acknowledge there is more being created in the viewer than what they explicitly intended to put there? There’s many studies and theories and practices revolving around what is laid out in the page. Or even in the flow and nominal succession of stages. But what about that invisible instant when two things clash?

The most web developers have concerned themselves is with transition states. Usually trying to even the journey, looking to smoothly transition from one state to the other. That’s a pre-editing stage of realization — make everything seem like it’s a continuum. One sequence. Film montage discovered that time (in it’s cinematic sense) is being created beyond the singularity of each screen, beyond shot-sequences. That the continuum is being sculpted at a higher level — in that whole dimension that transcends individual pieces, and gives tremendous creative power.

In a way, web design needs to find its own montage lessons to control their less tangible experiences, to control the effects that are being created when screens are switched (specially as the viewer is often choosing the path). When what is being designed is not just the specifics of a screen, or the abstract notion of a flow, but the gap between different fragments of an experience evolving in time.


  1. Truth be told, the last one was actually supposed to be a woman on a divan, casting the expression of desire on the actor. My apologies. But it functions the same way — I’ve grown accustomed to this variation of the experiment, as it’s the one I’ve constructed to carry myself, and enjoyed the more complex effect better.
  2. Described with precision by Eisenstein when he said a series of two film fragments is to be regarded not as their sum, but as their product.

Theme Experience (THX) in core WordPress

For the past couple releases of WordPress I had the privilege of working on revamping the admin theme screens, probably my biggest core contribution since developing Twenty Eleven. Working on the WordPress.com theme showcase was one of the first side projects I did at Automattic, when we were just Lance, Ian and me on the Theme Team; and I’ve worked on the many iterations since then, so I’m glad I could bring part of that knowledge to help improve the core theme screens.

The project was initially called THX38 and started as a plugin during the 3.8 release cycle. After some user tests we settled on a complete revamp of the experience, using client side technologies to make it faster and more responsive. The design removed most of the text in the screen, allowing people to focus primarily on the theme screenshots. (I’m personally fond of the arrow navigation system that lets you browse themes casually with the keyboard — maybe coffee cup in the other hand. It’s a somewhat relaxing way of looking at themes.)

It uses Backbone.js to power the client side code, something many parts of the WordPress administration panels are starting to leverage. It’s a good bridge between the robustness of the current server side codebase and more dynamic technologies to help achieve better user experiences on the client — things like searching for an installed theme is instant. We managed to get this in very close to the release deadline. Another positive result is we ended up with leaner code than before, something that would help with future improvements.

For 3.9 (just released, go grab it or upgrade!) I worked on using the same architecture and UX to power the install-themes screen, which wasn’t touched in 3.8. This meant interacting with the .org API for querying themes. Again, this made it just in time. The end result is a faster and image focused browsing experience, that also paves the way for future iterations in the versions to come. That’s something I really like — we’ve now had two subsequent releases improving core aspects of the theme experience. This agile process aligns with the momentum that core WordPress development has been gaining since the last few releases, with rapid cycles during the year, and we are looking at even more improvements around multiple screenshots, filtering system, etc. We now have a solid base for it.

Thanks to everyone that helped getting this out there, during every milestone we passed — and my special gratitude to Shaun, Andrew and Gregory.


During hack day—a day devoted to trying things and exploring ideas at Automattic—I created Tonesque, a script that allows you to get an average color representation from an image. It’s inspired by the Duotone theme, but I wanted to make something much easier to integrate with any theme. It also uses a bit of a different color processing logic. I’m putting it to test here for my image posts to see how well it behaves.

A new tale on a past idea

Once again, time to move things around here and continue, with a renewed, dustless canvas, evolving a design that was started a while before. I have since removed most of the javascript but kept the direction initiated with the trilogue experiment intact, for the most part. The win being less time spent when navigating the different content sections and a more tight, balanced design. Also a brilliant excuse to work on hacking Toolbox yet again.

With this attempt, I strive to make the reading experience a tad more focused. I also got to redesign the picture gallery display with something more flexible and appealing —to me, naturally—, while still making use of WordPress core galleries.

The less friction towards content input should mean, theoretically, more content in the end; or perhaps better content. (That has proven to be a great value with the picture gallery, since it is quite easy to upload a new picture and populate that section without having to edit any code at all.)

Another point that encouraged this housekeeping was that the balance among javascript, CSS, and content was starting to feel constricted, impending further changes to the website. It was turning into a crystal tower for which any addition was a lure for catastrophes.

Note: If you have previously left a comment around here, my apologies on keeping it on the still-pending noria. That was in part due to the unfinished, precarious state of the respond section.

I redesign this place more often
than I write on it.