The most expensive part of an Adobe Commerce engagement is rarely the build. It is the rebuild that happens when the original agency leaves, the lead developer takes a different job, or your in-house team finally gets headcount and wants to take ownership. That second build is expensive because nobody documented the first one well enough for a new team to inherit it. The knowledge lived in three engineers’ heads, all of whom have since moved on.
Documentation is the lock-prevention discipline for eCommerce engineering. Without it, you are dependent on the relationships you have with the people who originally built the system. With it, you have leverage. You can switch agencies. You can move portions of the work in-house. You can buy yourself optionality, which is the most valuable asset a multi-year Adobe Commerce program can have.
Bemeir has both built greenfield Magento stores and inherited a lot of half-documented ones. The framework below is what we tell clients to put in place before they need it, because trying to document a system after the original team has already left is a project we have run several times and would prefer never to run again.
What good documentation actually looks like
Good Adobe Commerce documentation is not a wiki page that says “our store runs on Adobe Commerce 2.4.7.” It is a layered set of artifacts that lets a new engineer answer the questions they will actually need to answer in the order they will need to answer them.
There are four layers worth maintaining. The first is the orientation layer, which gets a new engineer productive in two hours. The second is the architecture layer, which explains why the system is shaped the way it is. The third is the operations layer, which tells you how to keep the system running. The fourth is the decision log, which records the choices that were made and the alternatives that were considered.
Most projects we inherit have a partial orientation layer, no architecture layer, a thin operations layer, and zero decision log. That is what creates lock-in. The decision log is the asset that prevents the next team from re-litigating choices that have already been made and learned from.
The orientation layer
The orientation layer is the document that gets read first when a new engineer joins. It should be short, sharp, and obviously maintained.
A working orientation layer covers seven topics: what the store is and who its customers are, what the major systems and integrations are, where the code lives, how to set up a local development environment, how to run the test suite, how to deploy to each environment, and where to ask questions when stuck. Each topic should be one to two pages. Total length, about 12 pages. Anything longer and engineers stop reading. Anything shorter and the practical setup steps get lost.
The single most useful test of an orientation layer is whether a new mid-level developer can stand up a working local environment from scratch in under two hours using only the documentation. If they cannot, the orientation layer is broken. Fix it before you do anything else. Our team at Bemeir’s Magento development practice treats the local-setup time as a leading indicator of overall documentation quality.
The architecture layer
The architecture layer is the document that takes a senior engineer from “I can run the code” to “I understand why the code is shaped this way.” It is the most underdocumented layer on most Adobe Commerce projects, and it is the layer that creates lock-in.
A working architecture layer answers five questions in depth. What are the major custom modules and what does each one do? How does the project structure GraphQL or REST API exposure? What is the caching topology? How do orders, customer accounts, and product data flow through the system? Where are the boundaries between Magento and the other systems the business runs?
For each major custom module, you should have a one-page summary that names the module, explains its purpose, lists its dependencies, and points to the entry points in the code. For each integration, you should have a sequence diagram that shows the data flow and a list of failure modes. For the cache, you should have a written explanation of which cache types are used, how they are invalidated, and what to do when a cache misbehaves.
The Adobe Commerce architecture documentation is a useful template for what the official version of these conversations looks like. Your project’s architecture documentation should not be a copy of those docs. It should be the project-specific layer on top of the platform’s defaults.
The operations layer
The operations layer is the document that lets a new engineer keep the system running without paging the original architect at 2am. It covers monitoring, alerting, runbooks for common incidents, and the routine maintenance tasks the system needs to stay healthy.
A working operations layer includes a list of every monitored metric and what each metric is supposed to mean, a list of every alert and what the responder should do when it fires, a runbook for at least the top 10 incident types that have actually happened on the project, and a calendar of recurring maintenance tasks like reindex cycles, log rotations, and security patch reviews. The table below is the format we recommend for the alert documentation.
| Alert name | Severity | What it means | First action | Runbook link |
|---|---|---|---|---|
| Magento cron queue depth high | Warn | Queue is backing up | Check consumer health | runbook-cron-queue |
| Indexer status invalid | Critical | Indexers are out of date | Verify cron, manual reindex | runbook-indexer |
| LCP regression on PDP | Warn | Page weight likely grew | Check recent deploys | runbook-cwv |
| 5xx rate above threshold | Critical | Application errors | Roll back recent deploy | runbook-rollback |
| Database connection pool exhausted | Critical | Connection leak likely | Restart php-fpm, investigate | runbook-db-pool |
For monitoring tooling specifically, the New Relic guide to alerting policies and the Datadog runbook automation overview are reasonable references for what mature alerting hygiene looks like across stacks. Adobe Commerce monitoring should plug into whatever observability tool the business has standardized on rather than living in isolation.
The decision log
The decision log is the artifact that distinguishes mature engineering organizations from immature ones. It is also the single most important document for preventing lock-in.
A decision log records every meaningful architectural choice along with the alternatives that were considered and the reasoning that drove the call. Each entry should be 200 to 400 words. The format we use looks roughly like this.
Title of the decision. The context, including what the business was trying to do and what constraints were in play. The decision itself. The alternatives that were considered. The trade-offs the team chose to accept. The expected reasons for revisiting this decision in the future.
A decision log entry for “we chose Hyvä over Luma for the storefront rebuild” might run 350 words. A decision log entry for “we wrote a custom indexer for inventory because the native one did not handle our virtual warehouse logic” might run 500 words. Either way, the entry should be written close to the time of the decision so that the reasoning is fresh.
The Architectural Decision Records project maintains a public template that is worth adopting if you do not have your own. The format does not matter as much as the discipline of writing them down. Without a decision log, the next agency or the next CTO inherits decisions without context and either reverses them at cost or perpetuates them out of fear. Both outcomes are expensive.
How to make documentation actually happen
Most teams agree documentation matters and then never produce any. The pattern is consistent. The fix is also consistent: make documentation a deliverable, not an aspiration.
Three changes work. First, tie 10 percent of every sprint to documentation. Not the last sprint of the quarter. Every sprint. Second, require a written decision log entry for any pull request that introduces a new module, integration, or significant architectural change. Make it part of the PR template. Third, run a quarterly documentation review where someone unfamiliar with a recent change tries to use the documentation to understand it and reports back on the gaps. Bemeir’s internal practice is to nominate a different reviewer each quarter so the documentation is tested by a fresh pair of eyes.
These three habits compound. After 12 months of consistent practice, the project has a documentation surface that a new agency can read in three days and inherit in two weeks. After 24 months, the project is durable enough that the question “what happens when our lead leaves” stops being a strategic risk and becomes a routine staffing event.
Documentation across platforms
If your business runs eCommerce on multiple platforms, the documentation discipline applies equally. The same orientation, architecture, operations, and decision-log layers should exist for any Shopify Plus build, any Hyvä storefront, any Shopware instance, and any BigCommerce implementation. The content differs by platform. The structure does not.
The longer-term payoff is portability. A documented system can be inherited by a new agency, partially brought in-house, or rebuilt on a different platform with clear reasoning. An undocumented system can only be reproduced with the original team or rebuilt from scratch with a new one. Documentation is what turns the former into the latter, and it is what gives you the leverage to choose your partner rather than be chosen by them.
If you are about to switch agencies, or if you are about to bring some Adobe Commerce work in-house, start the documentation work now. Six months of consistent documentation effort produces an asset that is worth multiples of what it costs. Six months of no documentation produces a hidden tax that you will pay every time the team composition changes. The math is not subtle. The discipline is the only hard part.
