The five Sanity mistakes that make your CMS frustrating to hand off
Sanity is flexible enough to build a CMS nobody on the marketing team can use. The five ways that happens, and what to do instead.
I hand Sanity studios to healthcare marketing teams for a living, and the complaints I hear about studios other people built are the same five every time. None of them is a limitation of Sanity. Every one is a decision that got made, or not made, in the first week of the build, and every one is cheap to get right then and expensive to fix after the content is in.
Here they are, in the order the editor meets them.
Mistake 1: everything is a page
The site has one document type, "page", and a page is a list of blocks. Providers are pages. Locations are pages. The FAQ is a page with a text block. It feels flexible during the build because the developer never has to decide what anything is.
The editor pays for it forever. Changing a phone number means finding every page that mentions it. Adding a provider means rebuilding their card on the directory, their bio page, and every service that lists them, by hand, three slightly different ways. Nothing can be listed, sorted, or filtered because nothing knows what it is.
The fix is structured types for anything that repeats or has its own URL: provider, location, service, FAQ, person. Keep the page builder for pages that are actually prose, which on a healthcare site is the homepage, the about page, and a handful of campaign pages. I wrote up the model I use in chapter 3 of the migration playbook.
Mistake 2: copies instead of references
The developer knew about structured types and still let the editor paste a provider's bio into a service page's rich text, because that's what the design showed and it was the fast way to make the mockup match.
Six months later the bio has been pasted into twelve pages and updated in four of them. A referring physician reads two different sets of credentials for the same cardiologist. The editor can't find all twelve, because the CMS doesn't know they're the same person.
The fix is that a section that shows providers references provider documents. It doesn't contain them. The layout lives in the section; the facts live in the record; the editor updates one document and every page follows. The same goes for locations, FAQs, and anyone whose name appears as a byline or a reviewer.
Mistake 3: no guardrails
Every field is a blank box with a one-word label. Nothing is required, nothing has a maximum length, nothing says where on the site the value appears or what happens if it's left empty. The editor guesses, and the guesses become the site.
A meta description of 400 characters. A hero heading with a line break in the wrong place because nobody said the field is a single line. A form field named "diagnosis" that quietly turned a contact form into a place patients type medical information. A navigation with eleven links because the schema allowed eleven.
The fix takes an afternoon: a description on every field saying what it's for and where it shows; required and maximum-length rules where the design has limits; validation that warns, not blocks, when something looks risky, like a form field key that looks like protected health information or a clinical post with no reviewer. Sanity makes all of this a few lines each. The starter I maintain does it for every field it ships with, and it's the part of a schema I'd least want to skip.
Mistake 4: no preview, or a preview that needs a developer
The editor writes a page, publishes it to see what it looks like, sees that it's wrong, and edits it live. Or there's a staging site, but it shows last week's content, or it's behind a login someone left the company with, or nobody knows the URL.
Either way the editor learns that the safe move is to change as little as possible, which is the opposite of what the CMS was for.
The fix is draft mode on the real site: a button in the Studio that opens the page with unpublished changes, and clicking any piece of text jumps to the field that produced it. Sanity's Presentation tool and Next.js draft mode do this; it's about half an hour to set up and it changes how the editor treats the tool. I'll write up the details in a separate post on preview workflows.
Mistake 5: nothing is written down
The build is done, the developer walks the team through it on a call, and that call is the documentation. Three months later a new marketing coordinator opens the Studio and sees forty document types and no idea which one to touch.
Healthcare adds a specific version of this: nobody wrote down who reviews clinical content, so nothing is reviewed, and the site that was supposed to carry a clinician's name on every condition page carries none.
The fix is short and in three parts: a task-based guide for editors (add a provider, change hours, publish a post with a reviewer, add a redirect), a one-page note for the manager about who approves what, and a handover for the next developer that says what was decided and why. Put the reviewer's name and the review date on the content itself as fields, so the rule lives where the work happens. I go through what each of those documents contains in How to document a Sanity build for a non-technical team.
What they have in common
Each of these is a decision the developer made for their own convenience during the build, and each one moves a small amount of the developer's work onto the editor permanently. A CMS handoff that works is the reverse: more decisions made up front, fewer left to whoever opens the Studio next.
If you're about to commission a Sanity build, ask the developer how they handle these five. If you've inherited one, they're also the order I'd fix things in.