willgarrett.iowillgarrett.io — ~/notes/005-design-for-maintenance.md
~ ❯ cat notes/005-design-for-maintenance.md

005-design-for-maintenance.md

Design for the week after launch

Architecture has to fit the people who will keep it running.

The architecture I want to recommend depends on who will be there after launch. A system maintained by a small team has different constraints from one with people dedicated to its infrastructure. The diagram should reflect that difference.

It is possible to design something that satisfies the requirements and still asks too much of its owners. Every additional service needs a release process. Every queue needs someone to understand what happens when work stops moving. A dependency can be convenient to add and expensive to keep understanding.

I find it useful to imagine an ordinary maintenance task before signing off on a design. Someone needs to change a field that appears in a report. How many places do they have to edit? Can they test the change locally? Will they need another team to release something first? Following that small task can reveal more about the design than another discussion about future scale.

Include the person on call

The person responding to a failed job needs a way to see what happened and decide whether it is safe to run again. If the design depends on that person remembering an undocumented exception, I consider that unfinished work.

I also want to know how the team handles an absence. If only one engineer understands the deployment, the plan needs to account for their holiday. A manageable system should let another person perform routine work with the access and documentation available to them.

That requirement can change a technical choice. A managed service may be worth its cost because it removes work the team cannot reasonably take on. A single application may be easier to operate than several services with tightly coupled releases. I want the tradeoff explained in terms of the people doing the work.

Budget for keeping it understandable

Maintenance needs time in the plan, including time to remove temporary arrangements. A migration path that leaves both systems running indefinitely creates obligations long after the new interface is finished.

When I review a proposal, I want the ongoing work to be visible beside the build effort. The client should be able to ask who will investigate a failure, how a new engineer will make a change, and which costs continue after the engagement ends. Those answers belong in the design while there is still an opportunity to simplify it.