Let’s not talk about cache invalidation, it will ruin your weekend. Instead, let’s talk about the other hard thing in computer science: naming things.

I recently jumped back into a Gatsby + Contentful project that I hadn’t worked on in a while. A lot has changed, including a whole bunch of new components and content types. If you haven’t worked with a headless CMS before, you need to know that content modelling is a whole thing — in Contenful, Strapi, Prismic, or Sitecore.

The new requirements mean that I have to spend a fair amount of time trying to understand the existing content model, and find ways to make it support the features I need to build. A pattern emerges pretty quickly: the names of the content types are not going to work, but it takes me a while to put my finger on why, or what the alternatives are.

Here’s an example. The original build includes a content type named ClientLogos. The content it’s used for is just what you’d expect: a grid of client logos, and a link to a page full of case studies or something. Unsurprisingly, the app includes a component named ClientLogos, and it dutifully consumes a GraphQL query response named ContentfulClientLogos.

As it turns out, the new UI design has something that looks kinda similar: a grid of company logos and a link, and also a title (“Partnerships”) and a description (something about the companies the client partners with to deliver their services.)

And here’s the problem: I can add the new fields in all of 30 minutes, close my laptop and go for a run. But that’s going to leave this system in an unhappy state — ClientLogos isn’t going to just render client logos anymore. It can render these other kinds of images too.

The more I look around, trying to map the new requirements to the existing content model, the more discouraged I get. The SolutionArea is going to be used for “Contact Us” content. The ClientSuccessStory is going to be used to profile a valued team member. And so on, across literally dozens of different content types, components, and GraphQL queries.

But then I see a shining exception: the JumbotronHero. It’s a perfectly-named thing, and I’m going to tell you why. Whether I’m a developer, a designer, a content editor, a marketing specialist, or anyone else on the project, I know intuitively what it’s going to implement:

1. A huge, full-viewport-width image
2. A huge <h1> tag
3. A huge call-to-action button

How do I know all this? Because the JumbotronHero has a name that is completely unconcerned about the content it consumes, and completely expressive about the feature it implements.

Fortunately, Contentful supports programmatic migration, including editing a content type’s display name¹. So I can start migrating:

• ClientLogos → CardWithThumbnailGrid
• SolutionArea → CardWithBackgroundImage
• ClientSuccessStory → CardWithPortraitImage

…and so on.

For each content type, I’m aiming for a name that describes the UI design it supports, not the content it’s used far. None of the names are as interesting as JumbotronHero…but that’s ok, it’s the content that’s supposed to be interesting. (We can’t all be the hero.)

Photo by Mehdi MeSSrro on Unsplash