View other posts

8 content modelling pitfalls to avoid

Date: 05 July 2020
Reading time: 10 mins

A man looking into the colourful sky in the night

Working with a headless CMS is often seen as the promised land, particularly from a developer’s perspective. The opportunity to open the development toybox and leverage the latest and greatest frameworks and patterns is mouth-watering.

However, there is much more to a headless CMS implementation than just frameworks and patterns. Content Modelling is a fundamental activity within a successful delivery. Get this wrong and, as the project develops, you will run into major problems for both content editors and your development team. More importantly, it can lead your clients to feel that headless CMS is not going to deliver what you expected, and worse, make you feel that headless CMS was the wrong decision.

Approaching content modelling in a thoughtful and futureproof manner is essential, acknowledging the capabilities and constraints of the CMS as well as identifying the optimum experience for clients.

For those new to content modelling, have a read through the blog posts by Michael Kinkaid - Content Modelling in Kentico Kontent and, bearing in mind the current climate, also check out the best practices on remote content modelling from my colleague Rick Madigan.

My top 8 content modelling gotchas

A group of people sitting in the meeting discussing something on the screen

For those about to start content modelling, there are a range of approaches and these come with their own pitfalls. I'm going to talk about some of the things you would need to consider when modelling content. So, here are my top 8 content modelling gotchas:

1. Don’t build all the content models without communication   

Within any project, there are several involved parties – experience design, product backlogs, technical architecture, and editors to name a few. Charging straight into content modelling in isolation, without room for adjustments, forces you to create the models based purely on the information you may have at that point in time. But as we all know, projects are living, breathing things where change and evolution are commonplace. The models you create may not cover the lean MVP requirements established by the product owner and will likely miss the discussions and adjustments coming from refinement sessions.

Work closely with all members of the team and keep in constant communication, acknowledging the subtle shifts in requirements. Establish key meetings and touchpoints to not only plan out content models but also to implement in line with development, avoiding wasted time.  

2. Avoid creating Content Types for individual Content Items

There are times within the content modelling where you need to create a Content Type purely for a single Content Item. An example of this could be the 'Home' type, where there are no other possible instances that could reuse that Content Type.  However, there are times where you create a new Content Type for the sake of subtle differences. Think about this in the bigger picture and these micro-decisions start to spiral and, before you know it, you've created Content Types for singular Content Items and have an expansive list that is hard to manage, increasing the complexity for development.  

Think about reusability wherever possible and, more importantly, be ruthless and actively seek out ways to consolidate content types.  

3. Add restrictions to the fields 

When modelling content, it is really easy to get carried away and create Content Types without consideration towards the target audience - your content editors. You can get caught up in thinking about the fields/elements that are required based purely on the designs. However, this lack of consideration can lead to ruin. Not adding restrictions to them can cause catastrophic issues in the long run.

For example, if you have a Hero Content Type and there is a limited amount of space for the title, summary text and CTA to show on the page, then not adding restrictions to the fields/elements would quickly break the content type output. As with the previous point, things can spiral quickly as you scale out to the bigger picture.

Carefully consider the different fields/elements in each content type and decide what character limits are needed, whether they need to be a required field or not, what sort of linked items are allowed within a given area and any other limitations to avoid your development team cowering under the desk from content model nightmares.

4. Avoid overcomplicating your content types 

 While reusability is a good practice, it is easy to abuse this and over-complicate your content modelling.

For example, you may build a content type and then decide to create sub content types within it to match a specific design. There are of course valid scenarios for this behaviour but, if left unchecked and used without consideration, you can soon find yourself with parent content types containing an unnecessary number of child levels or a large amount of unnecessary linked items. The content editor is forced to double or triple their cognitive load dealing with an overly complex content type. Not only that, but you may have also just gone over the quota for Content Items or Content Types which could incur big costing implications.

Your target audience is your primary consideration. Go for simpler structured data content modelling where possible and be smart with the potential linked items you introduce. Above all, avoid content type 'whirlpools' where it can get messy and costly, fast! 

5. Think first before using fixed Components in Rich Text fields/elements 

When you model content, there could be scenarios when you need to use a content type in a single instance. Examples of this are a Tweet within blocks of copy or even an “interrupter call-to-action” inside a piece of text. It's tricky to model these out as they don't sit within a given position with the text. Essentially, the content editor has the power and decides where they want to use this. This is perfectly fine but it is vital that the content editors understand that Components (the name for these single-use content items) are not reusable - unless they are converted to be reusable.

Also, spare a thought for the poor developers. If you need specific fields within the components to be included in the search as a filter, it is time-consuming and complex to trawl through the rich text field for modular content and extract the information you need.

Think carefully about where and when you allow for the use of Components within Rich Text and, of course, make sure you limit the number of different types that can be used. As always, think about the bigger picture and how it could impact features like Search. 

6. Not considering the different channels you need to serve 

An advantage of headless CMS is the ability to structure your content away from the traditional editorial experience – and all the limitations that a traditional CMS brings. Essentially, you are creating a content hub, managing the content within one place, and serving it to different channels.

The potential is awesome but if you don’t approach it in the right way, you can easily dig yourself a big hole and potentially overshoot the boundaries of your pricing plan.

The most common mistake is mixing content with channel variables. Let’s take the home page as an example. If you add all the metadata, page information, and web-specific information into the same Content Type as your homepage specific content, introducing a new channel is instantly problematic. Not only are you facing a nightmare separating out channel information from content but then content editors tackling different channels are falling over themselves. If you’re also introducing layout information into that Content Type (shame on you if you are!) that problem swiftly grows.

Strategy is everything. Don’t approach content modelling with tunnel vision. Yes, you may need to deliver an MVP but at least think about where this sits in the bigger picture. Thinking ahead about your channels will make your life easier in the long-term. And, definitely avoid layouts in your Content Types. That’s what a traditional CMS is for! 

7. Utilising the projects and spaces you have available

Headless CMS can be divided into open source and Software-as-a-Service (or Content-as-a-Service). For the latter, every vendor offers a range of subscription plans. Understanding what is available within those plans is important in making sure you can get the best out of the CMS. For example, if you have an unlimited amount of projects/areas in which you can create Content Types and Content Items, then use them! If you put all of your eggs into the one basket, then your basket is going to be very heavy and hard to manage.

Consider a piece of content manageable text that appears in multiple places within your project. In Kentico Xperience you would call this a Resource String. Now imagine you have a load of content items representing various pages and components across the site. These smaller pieces quickly get lost. Folding everything into a single project isn’t necessarily the right approach – even if you have a great search and filter.

Think about your content structure and consider how different spaces can be used to provide a greater content experience. For example, a project/area for your “resource strings”, another for pure content for Site 1, another for pure content for Site X (assuming multiple websites) and another for shareable content between your different sites. Organising your content modelling and content this way will make it easier to manage in the long term. 

8. Avoid the content hub overruling others when it is not needed 

There comes a time when you are dealing with different data sources and the Headless CMS is not the only piece of the complex architectural jigsaw. This isn’t the old world. The CMS is no longer the central store of everything. If you’re using a commerce platform and have product information, you don’t need to replicate information into the CMS. There are smarter ways to work with Custom Elements which avoid the pain that comes with unnecessary duplication. It’s the same for any system in this new architecture.

Map out your architecture thoroughly and understand where the core content and connecting data should sit. Clearly identify your master sources for each set of data and think about the mapping and relationships between data sets, e.g. core product information in PIM or ecommerce and associated rich media for products in CMS.


So, there you have it. That was my top 8 things to be aware of when undertaking content modelling. It can be time-consuming and challenging but also very rewarding when done correctly. As you can tell there are lots of ways to get it wrong and clearly-defined best practices can keep you on the straight and narrow. If you need any help with this contact me via email ( and I can help you with it further.

Related posts