How to document what your theme actually does
The most common failure in a theme migration is not a bug. It’s a feature that quietly disappears because nobody wrote it down.
Nothing looks broken. The site works. Six weeks later somebody asks why the wholesale pricing table stopped appearing for logged-in trade customers, and the answer is that nobody knew it existed.
Why does documentation matter more than the build?
Documentation matters more than the build because rebuilding known functionality is a solved problem, and rebuilding functionality nobody knows about is impossible.
A competent Shopify developer can reproduce almost anything on Horizon. What no developer can do is reproduce something they were never told about. Every migration that ends in a dispute ends there for the same reason: the two parties had different pictures of what the store did, and neither picture was written down.
The cost asymmetry is stark. Capturing a requirement costs a line in a document. Discovering it missing after launch costs a rebuild, a relationship, and whatever the functionality was earning in the meantime.
Why can’t you just ask the team what’s there?
Asking a team to list everything their theme does is asking them to perform a task humans are reliably bad at, which is authoring a complete list from memory.
Three things work against it. Mature stores accumulate changes over years, made by different people, several of whom have left. Much of what was built solved a problem that no longer feels notable, so it doesn’t come to mind. And the things people forget are systematically the things that matter — the edge case, the conditional rule, the fix somebody wrote at 11pm during a launch.
There is a related failure worth naming. When you ask someone what their store does, they describe what it’s for. They’ll tell you about the product page and the cart. They won’t mention that the shipping estimator behaves differently for one collection, because to them that isn’t a feature — it’s just how it works.
What can be extracted automatically?
Most of a theme’s functionality can be enumerated directly from the code, because a theme is a file system rather than a memory.
The following can be extracted without asking anyone anything:
| Extracted | What it covers |
|---|---|
| Templates and section order | Every template, and which sections appear on it in what order |
| Section and block schemas | Every configurable setting, and its current value |
| Snippets and their callers | Reusable code fragments and where they’re rendered |
| Custom Liquid and conditional logic | Display rules, including tag-driven conditions |
| Metafield and metaobject references | Which fields are used, and on which templates |
| App integrations | Every app embed, theme app extension, and hardcoded app snippet |
| Script tags | Anything injected into the theme layout |
| Locale files | Including custom string overrides |
| Redirects and structured data | The full redirect table and every schema type emitted |
| Base theme drift | Which files differ from the theme’s original version, and by how much |
Extraction typically accounts for 80 to 90% of a theme’s surface area. It’s also the part that gets skipped, because it’s tedious and because everyone assumes they already know what’s in there.
What can only come from your team?
Business rules and intent can only come from the people who run the store, because they exist as decisions rather than as code.
Code shows you that a condition exists. It rarely shows you why, or when it applies, or what should happen at the edges. A conditional block keyed to a product tag is visible in the theme; the commercial rule that governs which products get the tag is not.
These are the questions that surface it:
- What changes on the site during a sale or promotion?
- What’s different about your best-selling product page compared to a standard one?
- Does anything appear only at certain times, for certain customers, or in certain regions?
- What breaks or needs manual attention every time you run a campaign?
- What did someone build to fix a specific problem, that you’d notice immediately if it vanished?
- Is there anything you’d be embarrassed to lose but wouldn’t have thought to mention?
That last question consistently produces the most valuable answers, because it gives people permission to raise something they assumed was too minor to mention.
What’s a behavioral baseline and why does it matter?
A behavioral baseline is a recording of how your storefront actually renders and behaves, captured before any migration work begins.
The capture covers your highest-traffic templates across their real states — a product page in stock and out of stock, on sale and at full price, with and without variants — at each breakpoint. It records the rendered output, the network activity, which tags fire, and how key interactions behave.
The baseline matters because it changes what “correct” means. Without one, acceptance is measured against a document, so anything missing from the document is missing from the new build too. With one, acceptance is a comparison: if it rendered on the old store and doesn’t render on the new one, the difference shows up whether or not anybody wrote it down.
That’s the part worth understanding. A baseline doesn’t make documentation unnecessary. It makes documentation non-fatal — which is the only realistic goal, because no documentation of a four-year-old store is ever complete.
What does a complete requirements document contain?
A complete requirements document covers ten areas, and each requirement in it carries a testable acceptance criterion.
- Global and site-wide — theme settings, header, footer, navigation, global components, and every script injected into the theme layout.
- Templates — sections and blocks in order, per-section settings, conditional display logic, responsive behavior, empty and error states, and every custom template variant.
- Commerce logic and business rules — discount display, bundles, subscription eligibility, inventory messaging, shipping rules, market-specific behavior.
- Integrations — every app, where it appears, what it must do, and its Horizon status.
- Data model — metafields, metaobjects, functional product tags, and every template reference to each.
- Markets and localization — active markets, language handling, translation coverage including custom overrides.
- SEO and technical — URL structure, redirects, structured data, canonical logic.
- Analytics and tagging — every tag and event currently firing, with its trigger and payload.
- Baselines — behavioral, performance and accessibility.
- Open questions — the things nobody has answered yet, with an owner and a date against each.
Why acceptance criteria matter more than they sound
An acceptance criterion is the difference between a requirement that can be verified and one that can be argued about.
“The cart drawer works” is not a requirement. It’s a topic. Two reasonable people can disagree about whether it’s been met, and they will, in launch week, when disagreement is most expensive.
A requirement reads more like: adding an item from a collection card opens the drawer within 400ms, displays the correct variant image and line price, and increments the cart count. That can be tested. Nobody has to negotiate it.
Any promise about not losing functionality is unenforceable without criteria like that. It’s the single highest-value discipline in the whole exercise, and it’s the thing most often skipped because it’s slow to write.
How long should this take?
Documenting a mature store takes between a few days and two weeks, depending on whether extraction is automated and whether the store has been assessed before.
The bottleneck is rarely the extraction. It’s scheduling the session where your team confirms, corrects and adds the business rules — and then the calendar time waiting for sign-off.
Two practical points. Book that session at the start of the project rather than when you reach it, because it’s the item most likely to slip. And name a single approver with a stated turnaround, because a document sitting unreviewed for a week has consumed a week of the timeline.
What to do if you’re commissioning this
If you’re hiring an agency, the requirements approach is the most useful thing to interrogate before signing anything.
Ask how they’ll document what your theme does. Ask to see a redacted sample from a previous project. Ask what happens if something is missed. An agency that does this systematically will have an artifact to show you; one that doesn’t will describe a process.
Twelve questions to ask a migration agency → · How we document, build and verify →
Frequently asked questions
What should be documented before a Shopify theme migration?
Every template and section, all theme settings, custom Liquid and conditional logic, metafield and metaobject references, app integrations and how each was installed, scripts injected into the theme layout, locale overrides, redirects, structured data, and the business rules that only your team knows.
Why do theme migrations lose functionality?
Because discovery is usually done by asking people what the store does, and nobody can recall several years of accumulated changes accurately. The things that get forgotten are systematically the conditional rules and edge cases, which are also the things that matter.
What is a behavioral baseline in a theme migration?
A behavioral baseline is a recording of how the storefront renders and behaves — across real templates, states and breakpoints — captured before work begins. Acceptance for the new build is then a comparison against that recording rather than against a written checklist.
What is an acceptance criterion?
A specific, testable condition proving a requirement has been met. “The cart drawer works” is a topic; a description of exactly what should happen, in what order, with what displayed, is an acceptance criterion.
How long does requirements documentation take?
A few days to two weeks for a mature store. The constraint is usually scheduling the merchant review session and waiting for sign-off, not the documentation work itself.
Get your store documented, whatever you decide next.
A five-day Readiness Audit produces a written inventory of what your theme does, an app-by-app compatibility register, and a straight recommendation — including not migrating, if that’s the honest answer. $2,500, credited in full against a migration.
The document is yours either way. Several brands have taken it and done the build in-house, which is a legitimate outcome.
