Managed Services Handovers: the Good, the Bad, and the rest

I work in Managed Services, and we often get handover from the Professional Services when they roll off a project.
What makes a good handover to Managed Services/Sustained Engineering?
What do we want? What makes us sad?

Discussions on Managed Services vs Professional Services tend to focus on greenfields vs brown, handling multiple clients in a week, working with an unfamiliar codebase, etc. But what can PS do to make our lives easier in MS during the project or during handover? What docs/info do we want? What do we NOT want to see?

This is all my personal opinion. The purpose here is not to judge, but to highlight what I want and what I think would be good for others as well.


First, some context #

I have multiple clients at once (currently 5).
That means there’s a decent amount of time between time on a particular client.
This makes deep investigations into issues or behaviours difficult, as context is lost and allows time for more important bugs to build up in that time.

Anything I can be given that makes these easier is desirable.

Regardless of how good the handover is, I’ll always end up with a big list of notes in Notepad/Onenote/Obsidian for tips based on the context that I have (professional experience, knowledge, project info, etc) like “need to have Redis installed first” or “those settings are over there under the bush behind a fire”.

I don’t expect to be able to replace the notes, I just hope to reduce mental load and increase uptake of knowledge

I’m in Professional Services. What can I do? #

✔️ Good Practices, keep doing #

Sexy ResetTheWorld.ps1-style scripts #

These are something you can run after cloning the repo that stands up anything and everything needed to F5 the solution. It can also be run at any time to reset the solution back to a fresh state. Ideally: Create and seed databases, setup ACL entries if required, if builds require custom scripts, RUN THEM.

The remainder of these assume the above DOESN’T exist

A Code style setup (EditorConfig/Prettier) #

A sweet suite of tests #

Seed Data #

Well documented build pipeline yml OR Documentation around the pipeline #

Recently I spent nearly an hour looking between the build script, Azure, and AWS looking for where this variable was coming from. In the end, it was being set invisibly in the build step, BUT I did learn that some variables come from Azure Pipelines and some come from AWS Parameter Store. Very useful to know.

Infrastructure and Business logic Diagrams/Documentation #

Explicit versions #

Mobile or Simulator setup AND Cross platform instructions #

Other #

❌ Bad Practices, consider not doing #

Workarounds/hacks #

Magic strings/tokens #

NOT having a local override for dev settings #

Utilising uncommon things without documentation #

If it took you a while to figure out, note it down somewhere

Logging, how does it work? #

One interesting example was around naming, and there was an entity called unedited <things>, which sounds like it should mean the thing wasn’t edited.
While technically true, it wasn’t quite how it sounded (it created a copy which was the new version, and thus considered “unedited”)
THAT is the kind of thing that needs a comment.
It might have been correct domain language, but it was confusing to me as an incoming outsider.

Ultimate super excellent uber goal #

docker compose up

Full dev environment in Docker.
No local installations or setup except docker.
All development in Docker. All running in Docker.

I believe things are heading that way, and that is quite exciting, but we do need to set our future selves and colleagues up for that success.

If there was a discussion or decent research required in the team, write it down for people later!