A website rewrite can give its users a familiar screen and leave its next maintainer with an unfamiliar application. Someone still has to find the rule behind a wrong number, work out why a save failed, and make the next change without breaking the last one. That person belongs in the framework discussion.
In the Dayton Hash modernization work, the frontend direction changed from Nuxt/Vue to a fresh modern Angular/TypeScript application. The intended maintainer’s experience with Angular upgrades helped drive that choice. Familiarity with the tools was a practical consideration: the application would eventually need work from someone other than the person building the replacement.
That doesn’t make “use what we already know” a sufficient architecture rule; sometimes the existing approach is the problem, and learning a different tool is worth the effort. But the learning is part of the cost; it doesn’t disappear when the new application passes its build.
There’s also a difference between knowing a framework and knowing what a particular application does with it. A developer can be comfortable with Angular and still have to excavate three layers of abstractions to find out why an event won’t save. Familiar tools can support unfamiliar mysteries.
For a handoff, give the intended maintainer a small, complete task. Here’s a fictional example: an event editor should reject a location that contains only spaces. Ask the maintainer to find the rule, change it, update the relevant test, and run the result. The exercise should include what the user sees when the save is rejected, so it reaches beyond getting a test to turn green.
Then perhaps have the maintainer investigate a failed save in the test environment. Can they tell whether the form rejected the input, the server rejected the request, or the browser never received a response? Those cases lead to different fixes. The instructions and diagnostic messages need to help them make that distinction.
Let them try with the material you expect to hand over. If you have to narrate every step, write down where the explanation was needed. “Ask me” is a dependency, even if it doesn’t appear in the package file.
Do this while the first complete feature is still small enough to change. A calendar page that displays events is a useful start, but a working edit needs the rest of the trip: opening the right record, checking permission, saving the change, and showing what happened. Following one task through the application exposes decisions that a tour of the folders can miss.
The exercise may reveal missing instructions. It may also reveal a needlessly complicated implementation, an error message that hides the cause, or a development setup that depends on something installed on the original developer’s computer months ago. More documentation won’t fix all of those. Some belong back in the code.
And make the maintenance arrangement explicit. Experience with the chosen framework doesn’t volunteer someone for the job. Agree on the work they’re willing to take on, give them time to examine it, and leave room for their feedback to change the design.
Before calling the handoff complete, let the next maintainer make a change and explain a failure. Keep track of where they need help. That’s the next work list.
—jhunterj