How to document a Sanity build for a non-technical team
Three readers, three short documents, and one test that tells you whether the handover worked.
The documentation for most CMS builds is a recording of the handover call. It's an hour long, it was accurate on the day, and nobody has watched it since the coordinator who was on the call left. The next person opens the Studio cold.
Documentation that survives is short, split by who's reading it, and kept where the reader already is. Here's what I hand over with a Sanity build for a healthcare marketing team, and the test I run to know it's enough.
Who is the documentation for?
Three people who want completely different things, so three documents, none longer than a few pages.
The editor wants to do a task: add a provider, change a location's hours, publish a post. The marketing manager wants to know who can do what, what needs approval, and who to call when something breaks. The next developer wants to know how the thing is built and why it was built that way. Writing one document for all three produces something nobody reads.
What goes in the editor guide?
One page per task, in the order the tasks come up, with a screenshot each.
For a healthcare site the list is short and stable: add or update a provider, add or update a location, add a service or condition page, publish a post with a clinical reviewer, change the navigation, add a redirect, update a legal page. Each page says where to click, which fields matter, where the content appears on the site, and what happens next (it's live in a few seconds; here's how to preview first).
At the top of the guide, three rules that don't fit any task. No patient details in the CMS, ever, including in a draft. Every image gets alt text. Anything that makes a clinical claim carries a reviewer's name and a date.
What isn't in the editor guide: anything about how the site works. The editor doesn't need to know what a webhook is. If a task needs that explanation, the task is too hard and the build should change, not the guide.
What goes in the manager's page?
Roles, approvals, and contacts. One page.
Who has which role in the Studio, and what each role can do. Which content needs a clinical reviewer, which needs legal, and what "reviewed" means in practice (the reviewer's name and the date on the document). What to do when something's wrong: what the team can fix in the Studio, what needs a developer, and how to reach one. If the site is on a support plan, what the plan covers and what the response time is.
This page is also where the decisions live that a manager has to defend later. Why there's no chat widget. Why the contact form has no free-text field. Why analytics don't fire until a visitor consents. Each in a sentence, with a link to the fuller explanation, so the manager can answer the question without calling anyone. On my builds those explanations are the compliance chapter of the playbook.
What goes in the developer handover?
Everything a competent developer who has never seen the project needs to make a change safely, and the reasons behind the choices they'd otherwise be tempted to undo.
The practical part is a README: how to run it locally, the environment variables and what each is for, how it deploys, where the schema lives, how the revalidation webhook is configured, how to add a document type end to end. The starter I maintain has a worked example of adding a type that I copy into every project's docs, because it's the most common change a client asks for.
The part that's usually missing is the decision log: a list of choices, each with what was decided, why, and what it rules out. Consent state in local storage rather than a cookie, and why. Exact-match redirects only, and why. No tag manager, and why. The next developer will be asked to add a tag manager within a year; the log is what lets them say no with a reason instead of yes with a shrug. The starter's decisions file is the format.
Where should it live?
Next to the work. The editor guide belongs inside the Studio, the developer docs belong in the repository, and the manager's page belongs wherever that team keeps its operating documents.
A PDF attached to the handover email is where documentation goes to be lost. In the Studio, a "Help" entry at the bottom of the structure that opens the guide means an editor who's stuck is one click from the answer, in the tool they're stuck in. I keep the guide as documents in Sanity itself, so the team can correct it when a screenshot goes stale, which they will.
Keep it short enough that someone will actually update it. A forty-page manual is accurate for a month. A six-page guide gets fixed when it's wrong.
How do you know it's enough?
The handover test. A new editor, ideally someone who wasn't in any of the build meetings, gets the guide and nothing else, and completes four tasks: add a provider, add a location, link the two, and publish a page with a reviewer.
Every question they ask is a gap in the guide, or a problem in the build. Fix the guide the same day. If the question is about the build, that's a change to the schema or the field descriptions, and it's worth making before the team has learned to work around it. When someone gets through all four without asking, the handover is done.
Then record the walkthrough call anyway. Not as the documentation, but as the thing people watch once, on their first day, before they open the guide.