Content modeling: Lessons learned from Clover

The next time you seamlessly pay at a donut shop, barber or outdoor market, thank Clover. The cloud-based Android point-of-sale platform has shipped more than one million devices to shops, restaurants and service providers all over the world.

Clover customers never have to say "sorry, the register's down," and they run their businesses more profitably thanks to web apps and third-party app integration.

In the recent webinar "Content Modeling: Practice makes perfect," Clover's Rachel Church, Senior Software Engineer, shared three web app-based projects and what they learned along the way with Contentful’s developer evangelist Amelia Winger-Bearskin.

Model once, publish everywhere

What's content modeling anyway? Content models give structure and organization to content. Modeling in a headless CMS requires a slightly different mindset from traditional CMSes. In Contentful, a web page is made out of building blocks called content types. These types are devised by breaking up blobs of content into smaller components that can be reused and shared easily. That makes it easier to deploy again and again across different apps and outputs: big screens, in-store screens or pocket-sized screens.

Right-size your content model

Clover chose Contentful to empower their content and marketing team to create and control content without relying on the engineering team. Their first project with Contentful was the company's homepage. With a small team and a single designer heading up the modeling effort, they ended up with 24 section types that could be used on three different page types for a total of 48 different content models. In other words, way too many.

The content model made sense to the person who created it but not to the content team that needed to use them. "It was one of the pain points we had," Church says. "People would look at all the fields and wonder, 'what was this supposed to control again?'"

“It could be overwhelming for people not used to working in this kind of system,” she says, "it's doubtful that anyone truly understands what's happening here or what every single field is controlling without diving into the code." They've since learned to take advantage of the "help" text option in Contentful, which clarifies what section does what.

She offers three fixes for content model overload:

1. Avoid creating new content models for variations of the same thing. "It would've made sense to combine some of them and use some true/false flags instead of devising a different model for every one."

2. Require hint text and validation for every field. The hint text is a quick and easy reminder of what the field controls on a page, while validation enforces the structure that the code expects. “I recommend making the validation as strict as possible when starting because it’s usually easier to loosen the rules than to make them more strict later.” Even if it seems clear while you are creating the model, it doesn’t hurt to document the intended usage of the field.

3. Always review content models with stakeholders. “Content modeling should be diagrammed and reviewed with stakeholders before ever adding any of the content models to Contentful. It’s much easier to whiteboard or sketch out a rough draft early on than it is to update/change the content models later.”

Your content models will change (and they should)

As Clover expanded into new markets, it outgrew the help site running on WordPress. As more countries and languages were added, the team needed more flexibility and localization capacity. Requirements were similar to the homepage project except with the additional need to optimize for search engines so customers could find information quickly.

It took weeks of back and forth between the engineering and content teams to build a total of 16 total content models. Some of those models were tweaked during the development cycle, too. “You really don’t get the content model right the first time. On every single one of these projects, it’s been an iterative process. Every time we think we have it, we come up with another use case, she says.”

Clover initially had a text field that allowed content authors to specify a list of countries that the help content applied to. It was later decided that this field should instead be a list of references to a ‘country’ content type so the engineers wrote and ran a migrations script that converted all of the content to this new structure with the help of the Contentful CLI tool.

Rachel’s suggestions for content modeling with future change in mind:

• Don’t try and future-proof your content model the first time. Meet the use cases you know you have now and leave room for later changes.

• Use the Contentful CLI tool to run migration scripts that can systematically alter your content model and migrate content to the new structure as needed. Clover follows an ‘expand contract’ pattern typically applied to database migrations.

Reduce, reuse, recycle...Or not

When Clover started selling devices directly to merchants in 2018, homepage content needed to reflect this direct-to-consumer market. The redesign was significant enough that it provided an opportunity to convert the original Clover homepage from Ember to React and to re-do the Contentful content models. This time, the team wanted to make things as reusable as possible and to limit the number of content models created. The engineers were provided the rough designs and broke the content into topics and assemblies that they found in a Contentful blog post. The goal was to create content that was completely reusable in any of the layouts. The teams built 13 assembly types for a content model that’s a lot smaller than the previous homepage. The assembly model allows content creators to put individual content types together to build web pages, documents, apps or other content products.

“We did a lot better in making the model intuitive and easy to use,” she says, “except that the content team didn’t use the content models as the engineers had predicted. Engineers were very excited about the reusability aspect, but when we looked back, only about 30 of the 450 subject entries were reused in multiple instances.” The content team preferred having duplicate content specific to the assembly they were using instead of creating a new subject.

Church recommended that the engineers remember that the end-user of the Contentful content models are the content authors. “It’s important to keep open lines of communication early in the process, so you’re building what the end-user really wants.”

“There really is a balance between things being reusable versus intuitive and simple”, she says. Expect there to be trial and error while building your content model but just remember that practice makes perfect.

Watch the hour-long webinar with Rachel Church, Senior Software Engineer, and Contentful’s Developer Evangelist Amelia Winger-Bearskin for a technical dive on Clover’s content models, challenges and key learnings.

Subscribe for updates

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