Patience and the right tools — the developer's guide to content modeling

Remember the good old days when we used to build “web pages”? We were in a “Microsoft Word”-driven world and we wanted to use the same tools when managing content for the web. So we basically ended up with twelve pages powered by twelve different “Microsoft Word” documents created with a WYSIWYG editor.

The problem with this approach today is, that you never know where your content will go. It can be another website, it can be an app; it can be the always empty smart fridge in my kitchen.

The solution to this problem are small reusable blocks of content that can be used to piece together something unique. It’s like Lego in a sense. A million tiny pieces that I can use to build whatever I want.

But let me ask you a question though: How often do you build something with Lego without eyeing through the manual? And if you usually just wing it, how often do you fail?

Never? Yeah… that’s what I thought. It’s the same for me, and it took me a while to realize that it’s not my fault. Creating something unique with a set of standard building blocks is hard. The same goes for content modeling. It’s tough, and nobody gets it right the first time.

Ways to survive the challenging task of content modeling

How can you succeed with your content not knowing where it will go, and what the future requirements will be? For me, the solution boils down to three things:

1. Share and reuse of content models

Last week I came across angularjs-contentful-starter by Josh Hebb. As the name discloses, it’s a boilerplate in the form of an Apple store site to start Angular development with Contentful quickly. I’m a frontend developer by heart, but I have to admit that developing in the “Angular world” is hard for me. Too many things changed over the last two years, and I’m not keeping track of it.

I expected a painful day of setup and dealing with JavaScript Fatigue, but the project turned out to have a hidden gem: a helpful setup process so that I can create an Angular app powered by data from Contentful in minutes. That’s an excellent developer experience.

So how does it work? The project provides an npm init command which not only installs dependencies but also helps me to set up a Contentful space inline with the codebase so that I don’t have to figure out the content modeling myself.

The file contentful-export.json (created with our contentful-export tool defines all the entries, assets and content types and is then picked up by contentful-import to get my space ready for this certain use case.

Let’s think about that for a minute? How cool would it be if we would all start sharing code including the needed content model? I mean pick a boilerplate, set up the Contentful space – done! No server configuration required. Editable, scalable and up in minutes! And do I have to worry about the content model? No – because project includes it! This sounds like heaven to me.

You might have heard of the terms zero-config projects or toolkits. This approach is precisely what I’m referring to.

For me the approach for upcoming Contentful powered projects is clear. I’ll keep a collection of working, logical content models and I will then replicate them to have a full-speed start for new projects. And so that we can all benefit from the community we set up a new category in our community forum contentfulcommunity.com. For example this content model powering my private site. I would love to learn more about how you use Contentful.

2. Analyze and visualize your content model

When you have figured out your content model, or found a nice starter project to import, the next hurdle is already in front of you. You start tweaking and changing the content structures. Content has the same lifecycle as a codebase. Just because it works for your project today doesn’t mean that it will work for tomorrow. If you want to keep your content model tight and maintainable, changes and refactorings are unavoidable.

What always helped me (and this is true for coding and content modeling), is to take a step back and visualize what I’m dealing with. It can be classes in my source code or relationships between content types in my content model. It is easy to get lost in details and to miss problems that are in the bigger picture. My favorite tool to find problems in my content model is contentful-graph by Yaraslau Kurmyza. It’s a command line tool to visualize your content types and make the structure and connections between them visible.

This command uses the Content Management API to fetch all the configurations and then graphs them out like so:

The visualization helps us to answer the following questions:

• Are the content types structured the most efficient way?

• Are the field names consistent?

• Do all the relationships make sense?

• Are there too many relationships?

• Is it time to restructure?

I found this to be a great help figuring out a scalable content model. And it also supports me in my daily coding work. Apparently, I can not remember all the field names or relationships between items when I’m building a product, and that’s why a printed version of the current content model is always next to my desk. This way I can be more productive.

Speaking about me – I don’t mind to create the visualization via the command line, but I could imagine that this is not the most convenient thing for your editors to do. And surely you don’t want to create a lot of PNGs by hand.

Yaraslau additionally built a web app which can do the same thing and more. Head over to contentful-graph.yaraslav.com, enter your space ID and API tokens, and get the graph visualization right in the browser. There is also an interactive version of your content model which can be helpful when dealing with complex content models.

3. Evolve and iterate your content

The last step to master content modeling is the trickiest one. How do you deal with changes when you have a lot of content set up? Field or relationship changes are difficult to do then because you have to change existing entries to perform changes and evolve your content.

Thankfully Contentful released the contentful-migration-cli a few month ago. With this tool, you can write migrations and automate content model transformations with code. So what can you do with it?

Content type operations

The contentful migration CLI gives you the possibility to perform scripted content type operations. These go from creating content types over editing them to changing field IDs. Of course, the mentioned operations (except for the changing of a field ID which is currently not possible in the web app) still can also be done manually in a productive way, but I think it’s a good start getting used to automated migrations today.

This way you get ready for significant changes in the future. At some point, you will have to deal with different environments, and even tiny changes that need to be performed in more environments than one can become cumbersome.

After I visualized my content model, I saw some issues right away and started evolving.

Deletion of unused fields

I’m editing the content of my site several times the week, and I am used to the structures I see in the editor interface. Looking at the content model visualization, I immediately saw fields that I ignore for months without thinking about them.

The fields screenshot, venue and hotel seemed to be a good idea a year ago. It turns out they’re not useful at all. How could I script them away?

Copy

The needed code is only a few lines of JavaScript, and I could have done this in the web app, too, but writing a proper migration, on the one hand, is more fun (because it’s nerdier) and on the other hand is more scalable. I can now apply these changes to any copy of this space and any environment I have to deal with.

Renaming of field IDs

Next thing I discovered was that I use two kinds of similar content types for posts which is probably not a good idea in the first place and I’m considering merging them at some point. What bothered me, even more, was, that the two content models defined fields for tags and categories. I know that these are the same thing, but I didn’t notice this difference when I set up the content model. Remember – content modeling is hard.

The web app does not support these kinds of changes, and this is where the CLI shines. A few lines of JavaScript can help me clean up.

Copy

Content transformations

Dealing with existing content is harder than configuring content types. Let me show you an example.

Deriving entries from another

My content model at the time included an “event” type which has fields for the country and city the event takes place. This structure worked great, but after adding new events for over a year now I started to see redundancies and duplicated data. Most conferences happen every year which means that I have to put in the information of the city and country also for every event. I thought that it would be a good idea to get this information out of the event type and put it into a conference content type that only holds the city and country information.

My current Contentful space includes 96 events. To perform content model modifications on this scale, I would have to create new conference entries for most of them and then also update all the existing event entries to reference the newly created conferences.

There is no way to do this by hand. And this can be quickly done with a migration. I have to admit that this example is a bit more complicated and is not the focus of this article but it took me an hour to write a migration that performs all these repetitive tasks in a few minutes.

In case you’re interested in the migration you can find it in this gist.

Tooling and patience are important tools to master content modeling

The most important thing is that I should never fear to make changes to my content structures. Thought through and scalable content models do not happen overnight and usually are the result of many many iterations. It’s just a matter of the right tools, openness to change and enough patience to create something great tailored to my needs.

And I think that’s alright because I don’t think any person out there can build a beautiful self-made lego artwork on the first try either…

Note: This is the written version of the talk "Content modelling is tricky – ways to survive"

What's next

If you want to further explore the land of content modeling then our knowledgebase article Topics and Assemblies is a great next step.

If you would like to try your hand at content modeling with Contentful, try our community edition for free.

Start building

Use your favorite tech stack, language, and framework of your choice.

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.