Issue 42

Managing your content model over time, part 6

The anatomy of a content model specification

We’ve spent most of the last quarter at Model Thinking talking about managing your content model over time.

• ​Part 1: Your content model isn’t finished​
• ​Part 2: Who owns the content model?​
• ​Part 3: The most dangerous content model changes​
• ​Part 4: Not every team should manage a content model the same way​
• ​Part 5: Who needs what from your content model documentation?​

This issue—I think?!—brings the series to an end with a look at how to design the content model documentation or specification.

Versioning

I usually version the content model similar to how software teams would version software in the days of installable apps. Minor changes were a point increment, such as 1.0 to 1.1. A major refactor to the content model (multiple new content types or significant changes to existing—it’s subjective) would be a version increase, like 1.3 to 2.0.

I don’t want to lose the historical context of the model’s evolution, so I do not use an ongoing page. I like to have a separate page or document for each version number. So, 1.0 is one document. 1.1 is another.

The structure

Overview

I like to start with an overview of the content model to set the context. This overview includes who owns the content model, its status, links to previous and subsequent specifications, and a changelog.

You might consider adding an executive summary and a high-level full-system content model diagram in the overview section. As the content architect, I love to have a detailed full-system content model diagram for my own reference and some stakeholders will also appreciate this. However, this level of detail can cause more problems for the many stakeholders who aren’t as hands-on. Instead of including the diagram visually, consider linking to it instead.

If you’ve set up design principles for the content model, they should go in this overview section. You might want a section or subsection about system-wide governance and conventions.

Then, I move on to individual content types.

Content type summary

Use headings to give the common user-facing name of the content type, then provide a description of the content type, such as what type of content will be in that content type as well as its purpose and possible uses.

The common name that you used in the heading might change over time, but the name—or identifier—that developers use when accessing the content type via APIs rarely will be changed. It’s a good idea to include this API identifier in your specification.

This is a good place to include access rights information for whatever roles you have in your content management system (CMS). For whatever roles defined in the CMS, I like to list each and specify “yes” or “no” for each permission such as create, read, edit, delete, publish/unpublish, archive/unarchive.

I also like to include a simplified diagram of the content type and its immediate relationships. If I’m creating a specification for a stream-aligned team that owns the end-to-end work, I might include design mockups of how the content type might appear in a user experience. Mockups might also be helpful for a specification used by a platform team or a complicated subsystem too, but the mockups or screenshots might be harder to keep up with.

Additional notes might be handy in the summary too, such as notes about when the content type may need refactoring.

Then you reach the question of how to document all of the specifications of the content type. Do you include that here? My recommendation, based purely on practicality, is that the content type specifications do not live here. I suggest linking to them from the content type summary.

Content type specification

In many CMSes, the content type’s content model contains a surprising amount of information. The level of detail to record here surpasses what makes sense to put into a traditional document like Google Docs or Confluence or even Notion.

Note: In Issue 5, I introduced my idea of content model fidelities based on work by Cleve Gibbon: conceptual content models, design content models, and implementation content models. Documenting the content type specification equates to the implementation content model fidelity.

In part 5 (Issue 41), we talked about what different audiences need to know from the content model documentation, and it’s reasonable to expect that developers and content strategists or content designers might need the granular information from the content type specification.

While a developer might prefer JSON, most content professionals need a more-user friendly reference. Therefore, I tend to use spreadsheets to document the content type specification. It’s fairly human friendly, and I imagine that the inherent structure of a spreadsheet could be transformed into JSON if absolutely needed.

I often make each content type a tab in a spreadsheet, and I try to set up each sheet to capture everything that the CMS vendor provides. This information varies by CMS, but I like to provide a place for the content type name, API identifier, content type description and then the individual field names, field types, API identifiers, validations, appearance, help text—and probably more, depending on the CMS.

Some notes:

• Validations differ depending on field type. You’ll want to decide how to handle this. I tend to have columns for every possible validation and gray out the ones that don’t apply to a particular field.
• If you’re on a cloud-based CMS, the vendor may add new field types or add new kinds of validation options, etc. This shouldn’t break your model, but it may mean updating your spreadsheet occasionally.

Having every content type documented this way gives a centralized place for the content strategist or editorial team to review field names, validations and help text, even prior to implementation. Make sure you have an agreement or governance in place if they will be using this to refine field names or help text. (I suggest a two-way discussion before updating validations.)

Other considerations

Platform teams

Everything above here probably works for both stream-aligned teams and platform teams, but if you’re documenting for a platform team, you’re documenting the contract between the platform and the teams that are consuming from it.

You’ll likely want to provide more information about how stakeholder teams should work with the platform—API information, query syntax, the “shape” expected in query results, change management procedures, information about breaking changes, and so on.

This information may take a different structure, format, and medium from the information above. It’s more like API documentation that developers are used to and less like a traditional document.

YMMV

Every organization has different dynamics and needs, so nothing I’ve written here is an absolute. Your mileage may vary.

Throughout this series, I’ve tried to provide frameworks that can help you think about what’s best for your situation and give you ideas of what’s helpful while leaving you the leeway to adapt for your situation.

I’d love to know what has been most helpful in this series. What was your a-ha moment? Have I left anything out?

A nascent resource

I’ve been wanting to provide a series of digital templates for content model documentation, but I’ve got a lot to learn about the “digital product” world.

If you’d be interested in buying a digital template, shoot an email to model-thinking@tripleoakenterprises.com to let me know your interest, and I’ll follow up.

Content Strategy at Work: Real-world Stories to Strengthen Every Interactive Project by Margot Bloomstein

Top of mind

• Best thing I read in the last 2 weeks: Dan Drapeau writes DXP Catalyst about the digital experience platform world. His recent digest talked about the emerging connectivity of AI agents via MCP servers. Drapeau clearly sees the need for companies to focus on the things I write about in Model Thinking.

• Something that made me smile in the last 2 weeks: It’s wonderful to have friends who just pick right up where you left off, even when you no longer live near each other. Last week, we spent time with those kind of friends, people we see every few months. On top of that, our normally reactive, protective dog accepted them into our house as though they never moved away.
• A pattern I noticed recently: People on LinkedIn who are newly on the job market (and in my feed, there’s a lot!) frequently announce that they are open to new opportunities and then declare the types of roles they are looking for (e.g. “I’ve spent X years at Acme Company, but now I’m looking for my next opportunity. I’m looking for a Sales Engineer role, a Customer Success role, or a Customer Support Manager position.”) I genuinely don’t know whether this is effective, and I’d like evidence. What’s the benefit of naming specific roles, versus talking about the value someone provides? Where does this behavior come from? Does it actually pay off?