Blog / Web management /
A decision record for website infrastructure changes
The infrastructure change worked. The new setup is live and the team has moved on. Months later someone asks why the domain uses that service, why the email records were left alone, or why one bit of the old arrangement is still there.
A decision record answers those questions before memory becomes the only source. It explains the problem, the options considered, the chosen action and the conditions attached. The aim is a useful operational note, not a novel about a hosting account.
In the hosting, DNS and SSL side of my Nivonix work, these decisions belong to connected services. Writing down the boundary matters because a change meant for the website can touch something the website team doesn’t own.
Start with the problem and its scope
Describe the issue that made a change necessary. Be specific about the affected service and customer task. A performance concern, an unreliable support route and an unclear account owner may require very different responses.
Record what the proposed change includes and what decisions belong to another owner. For a hypothetical hosting change, the website may move while email remains with its existing provider. That boundary should be visible before someone starts changing records.
Keep evidence and interpretation distinct. A monitoring alert shows that a check failed at a particular time. It doesn’t prove the cause or justify replacing a whole service.
Explain the options that were realistic
List the credible choices and why they were considered. These might include correcting the current configuration, changing one component or moving a service. Include the option of doing nothing temporarily where investigation remains incomplete.
Compare the requirements that matter to the business: compatibility, maintenance effort, ownership, support, cost and recovery needs. I don’t trust a provider choice made from a feature list alone. Check the workflow the team will actually operate.
I would record the reason a plausible alternative was rejected. That saves the next maintainer from reopening the same suggestion without knowing its limitation. The explanation can be short, provided it refers to the relevant requirement.
Name the decision and its assumptions
State what the team approved, who approved it and when. Include assumptions that could change the judgement, such as a dependency remaining supported or another team retaining ownership of a connected service.
An assumption isn’t a fact to hide in confident wording. Make it visible and say how it will be checked. If the decision hangs on a provider confirming a capability, record the confirmation or keep the approval conditional.
Document important unknowns too. A change can be reasonable despite uncertainty, but the uncertainty needs an owner and a way to shrink it. “We’ll see” is a poor operating plan when a customer journey depends on the result.
Connect the decision to the change plan
Link the implementation instructions, inventory and planned timing. Identify the person carrying out the work and the people who verify the affected services. The record should make responsibility traceable without duplicating every technical step.
Describe the important checks before and after the change. For a domain-related adjustment, those checks may include website access, form delivery and any separately managed services identified in the dependency map. Choose checks that fit the actual scope.
Keep secret values in the approved system. A decision record can identify the account owner and location of operational instructions without exposing credentials. The document needs to remain safe to share with the people who must understand the change.
Write the recovery decision before the release
Explain what would cause the team to pause, reverse or escalate the change. Record who can authorise that action and what evidence they need. A rollback route is useful only if the team understands when and how to use it.
Be honest about limits. Some changes can’t be reversed instantly, and restored configuration may not bring back data created after the transition. Document the service-specific limits with the people responsible, and don’t promise a universal undo button.
Keep the previous state or a suitable reference available where the process requires it. Check that the person expected to act can access the necessary records. A recovery plan locked inside an unavailable account is a frustrating form of decoration.
Close the record with observed results
After implementation, record what changed, the actual timing and the verification completed. Link any incident or follow-up task. Do not silently rewrite the original reasoning to make the result look inevitable.
Review whether the assumptions held. If the change revealed another dependency, update the service map and assign the remaining work. Completion may include a known limitation, provided it is clear and owned.
Finally, add a trigger for reconsidering the decision. A provider change, a new business requirement or a replaced integration can make a once-sensible choice obsolete. The record should help the next decision, rather than protect the old one from scrutiny.
Make the record easy to find from the service it describes: link it from the infrastructure inventory and give it a title that names the decision. If a later change replaces the arrangement, keep the old note but mark its status, so nobody has to guess from the document’s age which one is current.
Related reading
- What to prepare before a website host changes support teams
- A process for reviewing vendor access to a website
- How to document recurring website maintenance decisions
Take the next infrastructure proposal and write its problem, chosen action and recovery owner before implementation begins. Which assumption would you most want verified first?