Issue 39

Managing your content model over time, part 3

We’re in the midst of a series about how to manage those content models over time. If you’ve been following along, you should know the mantra by now: Expect your content model to evolve.

In part 1, we looked at documenting your content model. In part 2, we talked about ownership and governance. Here in part 3, we’re going to look at the kinds of changes your model might face over time. Some changes are riskier than others, so let’s take a look at a taxonomy—a risk ladder, if you prefer—of content model changes.

A taxonomy of content model changes

It’s useful to think through the types of changes that might happen in a content model, because each has slightly different ramifications.

A word about migrations: Any time you are making structural changes in the CMS, you need to be thinking about something called a migration and how you get from the current state to the future state. Changes to the model may need to be scripted in a multi-step process to safely move from the current to future state. You’ll often need to create the new piece of the model, and then populate it with new or duplicated content. Sometimes the model changes may also require migrations and transformations of content in the affected content types. (Like breaking one field into two.)

Let’s look at the 4 main kinds of content model changes.

Adding new content types

The safest type of content model change would be adding an entirely new content type. Theoretically, anyone could add this to production using a visual content model editor (if applicable), but I recommend sticking with the same process as you’d use for any of the other changes.

This way, you can make sure that teams know what the content type is for and how to work with it. And, my hunch is that you’d rarely just add a content type without also making a change to existing content types.

Changing existing content types

The most common change you’ll make to your content model is modifying existing content types. There’s a taxonomy to this too (roughly from safest to riskiest):

• Adding new fields (including references/links to other content types)
• Changing field labels and help text
• Changing content type labels or descriptions
• Changing existing field types or appearances
• Changing field-level validations
• Retiring fields

New fields are usually pretty straightforward system-wise, but you want to be sure your process accounts for change management with stakeholders.

You can usually change field labels and help text safely via the CMS’s content modeling tools, but there should be agreement in your organization about how you go about these changes. As long as you’re only changing the labels and not the field ID that APIs use (which often can’t be changed in the UI), your main concern is the author experience.

Changing content type labels and descriptions (if applicable) is similar to changing field labels. If you’re not changing the content type’s API ID (which usually can’t be done in a UI), you mostly need to be worried about disrupting the author experience.

In many CMSes, you can have different kinds of fields, such as long text fields, short text fields, number/integer fields, date fields, media fields, and more. Any change of field types should be handled by migration. You’re changing the data structure of the content type. For example, the change from a short text field to a long text field significantly changes the content type. Likewise, a short text field that becomes a number field is a major change to the data and meaning available to developers.

Often, a CMS may also let you set the appearance of a field. For example, a short text field might be set to appear as a text input, a dropdown, radio buttons, or checkboxes. Changing the appearance is something you might be able to do in the CMS’s content modeling tools, but you should probably handle with a migration, just to be safe.

It’s probably not uncommon for a content strategist or a content operations specialist to realize that a required field should be optional or vice versa, or that content errors could be reduced by having some sort of validation of the content entered in a field. This kind of change MUST be made in coordination with software developers via a migration.

If you have 10,000 entries and 2,800 of them have an empty field that you make required, you’re going to have a big problem on hand eventually. It probably won’t hit you right away, but complaints will start coming in. Other validations changes might bring immediate problems, and some of them could potentially cause down time for your published site.

Then we get to retiring fields as the riskiest change to an existing content type.

Deprecating fields

Retiring or deprecating fields earns its own subheading because of the complexity and risk involved.

It’s risky to remove a field from an existing content type because it’s hard to know where that field may be used or the impact on existing experiences if you want to remove it.

Let’s say that you have a short-text field labeled “Location” and your authors have used the field inconsistently. Some have put in GPS coordinates, others have typed in addresses, others have put city, others have put state, and others have put city and state together. You’ve updated the model to have more clarity, so you’ve adding four new fields: street address, city, state, zip code. At this point, you don’t need “Location,” so want to remove it.

If you simply remove that field via the CMS content modeling feature, you may break the “Find a store” feature on the website, you may mess up each store’s listing page, or you might break some CMS-adjacent business tool.

Simply removing the field also removes the opportunity you have to run a content migration that transforms the GPS coordinates to the four new fields, or the single-field address into 4 fields, or populates the known fields from whatever else authors have entered. Once the field is gone, the data in it is gone too.

Software engineers might—depending on your implementation—be able to tell you where or if the field is being used so that you can work with experience teams to transition to the new fields and deprecate the old field.

But many CMS vendors allow hidden fields, so you can convert the “deprecated” field to hidden where editorial teams won’t see the field anymore, but it’s still available via API for experiences that use it. Then you can help experience teams update the experience to use the new fields.

Deprecating content types

The last type of content model change is removing or deprecating an entire content type. Maybe you had a “Location” content type with fields for street address, city, state, and zip code that you used for store locations.

But now your company has grown and decided you want a “Store location” content type, a “Warehouse location” content type, and a “Corporate office location” content type. (This is just a hypothetical situation with a hypothetical solution—not necessarily how I would tackle this.)

So you’ve created three new content types and you’re ready to remove the generic Location content type.

Again, you’ve got a content migration concern here. If the existing entries in Location were only stores, you could migrate all Location entries to Store location entries. Once you did that, it might seem like you’d be safe to delete the Location content type, but you’re not. Existing experiences are still looking for content of the Location content type, so you’d break those experiences (and possible crash a website) if you simply removed the content type and all its entries.

The content migration is part of the process, but you’ve also got to partner with stakeholders and teams that consume the content to make sure that they update their code and their queries to use the new model.

A wise practice

When thinking about changes to the content model, you should borrow from the software development concept of additive changes. My paraphrase: Focus on adding capabilities in a way that doesn’t break what’s already there. If you’re changing or removing something, it’s really likely that you’re going to break something.

Deane Barker on the Content Matters podcast in “Redefining the CMS for the AI Era”

Top of mind

• Best thing I read in the last 2 weeks: Michael Andrews wrote a nicely researched article about why using AI is so exhausting. He puts words to a lot of things I’ve been feeling, and dances around a frustration I have with the constant suggestions for next steps that sound good but aren’t where I want to go. There’s a ton of gems like “Knowledge work switches from realizing a state of flow – defining what matters and how to achieve it – to maintaining vigilance over a machine.” Check it out.
• Something that made me smile in the last 2 weeks: The international visitors here for the World Cup experiencing America with eyes of wonder—from BBQ to Bucees to Bass Pro Shops to Walmart and Costco to biscuits and gravy to severe weather. We may have our faults, but we take a lot for granted too.
• A pattern I noticed recently: We internalize a lot of cues and our actions that go along with those cues. En masse, I think you could call these patterns. My second child has just earned his driver’s permit, and we’ve been using an empty parking lot for some early behind-the-wheel experience. It’s been some years since our family had a new driver, and I find myself needing to extract my internalized patterns to teach the nuances of piloting a vehicle.