Issue 41

Managing your content model over time, part 5

Eight months ago, you started using a new content management system (CMS) to publish a new thought leadership section on your company website. There’s been some wins along the way, and now it’s time to build some new content types and expand the use of the CMS to power more of the corporate site.

Congratulations on the wins! And also on encountering that maxim we’ve been talking about the last several issues: Expect your content model to evolve. You’re in the midst of that now!

Do you remember why the content model was designed the way it was? Do you know who is supposed to have access to which content types? Do developers and content teams agree on where to get the right content from the CMS?

If you haven’t already, it’s time to start thinking about what goes into your content model documentation. That’s what we’re moving toward. This issue, part 5, is about who needs what from your documentation (which I sometimes refer to as the content model specification, or spec).

Here’s the entire series so far 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​

Stakeholders = audience segments

You’re reading a newsletter written by a life-long writer and content strategist. It’s inevitable then that I will tell you that you need to think about your audience needs before creating content for that audience.

You likely won’t have just one audience that needs information in your content model documentation. You’re going to have cross-functional team members or groups from different parts of the business that might need to understand something about the content model. While there may be some overlap in those needs, the different disciplines will have differing needs.

To me, stakeholders represent different disciplines, and each discipline is an audience segment.

Let’s take a look at some of the main disciplines that have a stake in the content model, and what their needs are. (Remember, you may not have these titles in your organization, but you likely have people filling these roles.)

Content architect

The content architect needs to know the content model in and out. They need both the 10,000-foot view and the 10-foot view. They need to know the content types, their relationships to other content types, the fields and field types, and validations.

They aren’t the ones deciding on roles and permissions (the content strategist probably is), but they likely are the ones helping build that into the content model specification.

Similarly, they might not be the ones deciding on help text (the content strategist or content designer probably is), but they may have input, and they are likely the ones putting that help text into the content model specification.

Content strategist

The content strategist and content architect have similar needs from the specification, but with some slight nuance.

While the content architect may be building the content model documentation, the content strategist is a collaborator and consumer.

While the content architect needs to know the high-level ecosystem and low-level details, their focus skews technical. The content strategist needs the high-level view to help drive the art of the possible and influence user experience decisions. They need the low-level details to steer governance and build a quality author experience.

The content architect needs to understand how the content types and their relationships enable or hinder queries for content. The content strategist needs to understand how content types and their relationships might form building blocks for the user experience.

It’s possible that one diagram or artifact might serve both users, but you might find that different diagrams serve the different user types better.

Engineering teams

In part 4 (Issue 40), I talked about team topologies, focusing on stream-aligned teams and platform teams, and understanding the difference is crucial for providing the right documentation for engineering teams.

So, the platform team needs more complete documentation. Platform teams need to understand how content model changes are managed, and they need to be able to trust that the content model and its documentation are dependable.

But any type of engineering team needs the documentation to give them the basics of the content model so that developers can query for content. It should give them content types, fields, and their API identifiers. Depending on the team, developers might also need to know validations, and in many teams, the developers administer the CMS, so they would set up roles and permissions, and they might need to know all the granular details for running content model migrations.

Design team

Many design teams might not be hands-on in their CMS, but I think it’s good to provide a level of documentation that helps them understand the shape of the content that will be in the system, so that they can understand the content that will drive their designs.

Some basic high-level content model diagrams, and a list of content types with overviews may suffice.

Product manager/technical program manager

Hopefully you’re thinking of your CMS not as a one-time project but as an ongoing product or program. If that’s the case, you may have a business-minded product manager or a technical program manager helping lead your team.

The product manager probably needs access to the same kind of high-level information as the design team would need—content model diagrams and basic descriptions of each content type. Many product managers might want to get more into details, and a technical program manager may benefit from the kinds of information that the engineering team needs.

Content/editorial team

In a perfect world, your content model should be pretty self explanatory to the teams working in the CMS on content. And most CMS solutions give you the option to add information to help content teams—such as content type descriptions and field-level help text, and maybe even custom error messages for fields with validations.

But this isn’t a perfect world, so you’ll want to have resources to help content teams know how to use the CMS. You might want to think about going beyond the content model specification with authoring guides, instructional videos, online courses—or more. These are all about how to use the CMS.

The content model specification itself is more of a resource—a reference guide. Some content teams may just need the high-level content model disagram and content type descriptions. Others may want to understand all the fields and validations and roles and permissions.

Executives/sponsors

Don’t overlook executives or sponsors for documentation. Consider a one-page overview that documents what they are investing in. Keep it short and high-level, covering value propositions and less on nuts-and-bolts of the implementation and more on business capabilities that the CMS enables. You might link out to other documents about the program.

Do you need 7 different versions of documentation?

In short, no. You might need to experiment with getting the balance right, but I tend to think of a single specification that contains layers of information that different stakeholders can overlook or examine depending on their need.

Managing Enterprise Content: A Unified Content Strategy by Ann Rockley and Charles Cooper

Top of mind

• Best thing I read in the last 2 weeks: Adalgisa Neves, from Cape Verde, wrote in USA Today about what her country’s valiant World Cup debut means. It’s a beautiful article about a beautiful run in o jogo bonito.

• Something that made me smile in the last 2 weeks: I was visiting a client in NYC this week and had the chance to visit the Summit Experience at the supertall skyscraper One Vanderbilt. The entire experience was delightful, even for those who weren’t wild about heights. What stood out was the photo experience. When you enter, you get a wristband with a QR code. As you progress through the experience, you can scan the QR code and get your photo taken. At the end, everyone in your group can scan their QR codes into a single kiosk to compile all the group’s photos into one album that you can buy digital copies for $25. Then each person can scan their QR code on your phone to download the album.
• A pattern I noticed recently: I was reminded how 25 years ago I learned that a visitor to the city feels that the subway trains and riders are all random, yet a resident starts to internalize the train schedule—there is one!—and learns the schedules of fellow commuters. It’s probably fair to label me as a structuralist but the subway makes me think that even a structured content system needs some mechanism for unstructured content.

Welcome to the 1 new subscriber who joined us since the last issue of Model Thinking.