How to Tame a Wild West Contentful and Gatsby Website (Using Our Gatsby Audit Checklist)

As a leading Gatsby agency, many clients come to us for rescue projects, needing help taming their Contentful and Gatsby marketing website builds that have become a Gordian Knot of scope creep, project assumptions, and a lack of strategic guardrails.

Contentful is a powerful, cloud-based, SaaS content management backend designed for developers. And it is precisely this last point that is the source of the problems clients seek us out to solve with their Gatsby and Contentful sites. The source of the issue is that development teams often hand off the site backend (which is in Contentful) to the marketing team through no fault of their own. That team takes quick advantage of how easy it is to change and expand the content model. But, as we know from a million Spider-Man movies, with great power comes great responsibility.

That developer focused CMS backend is just what developers want for a tool that is as often used as the data backend for a digitally native consumer product as it is for a marketing website: fast, flexible, and without assumptions (read: opinions). But for a platform to be powerful for a specific use case (in this situation, a marketing website), you need the right guardrails to create the optimum conditions required to balance flexibility with speed. As Contentful is focused on several different use cases, those assumptions are lacking. And without guardrails, a Gatsby + Content marketing site can become convoluted over time.

Here is the four-step process we use to tame a Gatsby Contentful site and set it up for future success.

Step 1: Perform a Gatsby audit

Do you know that old joke about what a med student with a C average becomes? (A doctor.) Well, I’m afraid that the Bell curve is everywhere, whether we are talking about internal medicine, designing bridges, or building websites.
That means the first step you need to take to deal with a convoluted Gatsby and Contentful build is to perform a full audit. When you buy a house and have a plumbing issue in the first month, it’s unlikely that it is the only issue you will find.
After dealing with this situation several times, we decided to operationalize this step.

Drawing on our years of experience with the platform, we developed a comprehensive eighty-point Gatsby audit checklist to assess a build for performance, SEO, security, and best practices issues. Running the audit allows us to surface the critical problems to clients (like security), identify opportunities to reduce technical debt, improve the overall stack, and get fully onboarded on the site code to make improvements efficiently.

You can download our checklist at taa.ag/gatsby-audit.

Step 2: Audit the Contentful content model hygiene

Now that we have our arms around the Gatsby source code in step 1, it’s now time to focus on the Contentful backend.
The interplay between the Gatsby-powered front end of a website and the Contentful backend is extensive and crucial. Poor content model hygiene will degrade the editorial experience for the marketing team.

Take the time to step back and full audit the current content model, asking questions like:

 

• Does reusable content have its content type and is referenced in other content types? For example, do you use an author content type instead of the author field on a Blog Post?
• Is the page building content model flexible for editors?
• Are there many singletons (content types with only one instance)? Singletons should be minimized.
• Does proper, consistent field validation exist across the content model? For example, the title fields on Blog Posts should be required.
• Do content types and fields have descriptive names, descriptions, and help text?
• Does every field have a proper 'Appearance' setting? For example, text vs. URL vs. dropdown. Check out Contentful’s guide for more information.
• Does the content have admin titles so that it can be easily identified?
• Are WYSIWYG fields being leveraged to control formatting and content?

Step 3: Perform stakeholder interviews to determine the ideal editorial experience

The last set of findings we need to gather is the marketing team’s expectations using the website. Think of your results in this step less as requirements gathering and more about defining what success looks like.

Forget what you have today on your site, what you think is possible with Gatsby and Contentful, and focus instead on the ideal editorial experience workflow. Start by conducting 2-3 stakeholder interviews with crucial marketing users of the website.

Most importantly, conduct each stakeholder interview individually; you don’t want one marketer’s opinions to impact the feedback you get from another (we are social animals; we have neurological hardwiring in our brains to weigh heavily what others say before speaking ourselves).

The stakeholder interview should be a conversation thread you follow naturally, but here are few sample questions to get the flow going:

 

• What works well today with the site?
• What doesn’t work well?
• Looking back, what is the best editorial experience you have ever had on a website, personal or professional? Why?
• What is a deal-breaker for you in terms of a backend website editor?
• Do you need to create landing pages for marketing campaigns? If so, show us some.

Step 4: Make a plan

You now have all of the input you need to develop a solid plan to revamp your website stack.

Start with the stakeholder interview results and define what success looks like by aligning the expectations of the marketing team into a single vision. Using the Contentful and Gatsby audit results, identify functional areas that need to be refined, deprecated, or rebuilt to provide support for the various expectations of marketing.

Once you have a list of ideal refinements, work with a technical architect to estimate each change’s level of effort. From here, you can prioritize (if needed) and create a project plan or sprint schedule to make these refinements.

Step 5: Define the guidelines.

The last step in this process is the most crucial. The secret to addressing technology challenges is to ensure you always fix things two ways: fix the issue and make a change to prevent it from happening again. Steps 1 through 4 are the process to resolve the issue; step 5 ensures you don’t find yourself back in this situation 18 months from now.

Take the elements from your plan and create a Contentful editorial policy document. If you have an internal company wiki or knowledge system, that is a great place to track it. The document does not have to be long, but it should be clear, concise, and opinionated. The policy document should state what kinds of changes are allowed to the content model, what isn’t, and when changes are made what standard they have to meet.

Include a review of this policy when conducting onboarding for new marketing and web engineering staff.