Migration madness: How to navigate the chaos of large cross-team initiatives towards a common goal

Co-authors: Lily Wittle and Cathy Ji

Introduction

The Gateway-as-a-Platform (GaaP) team at LinkedIn builds infrastructure to support our secure third-party integrations for our customers. LinkedIn features that require sending or receiving data from external sources, such as importing email contacts and sharing LinkedIn posts as tweets, use our infrastructure. 

In 2020, we sought to deprecate our legacy deployment backend, which impacted every third-party integration at the company, and spanned use cases across dozens of engineering teams. Migrating 600+ use cases to our new deployment backend required technical effort shared amongst 100+ individual engineers. Driving a cross-functional initiative (called a Horizontal Initiative or HI) at the scale of our project was a huge planning and coordination effort. Here we share our learnings, tips, and tricks for successfully executing distributed-effort, cross-functional initiatives. 

Chaos-navigating strategies

Large, cross-team projects can seem daunting. They require hours of work from dozens of different individuals, and there may be dependencies between different individuals’ work. Driving these projects is a huge feat of coordination, even when everything runs smoothly! Plus, it’s not unusual for unexpected issues to pop up along the way, requiring additional work or adjusted timelines. All of these factors often make large projects hectic, but planning, documentation, and communication can bring order to the chaos. These are some of the strategies we used in our migration to help it run as smoothly as possible. 

Get clients aligned with the benefits of the new system
Large migrations are notoriously a lot of work and generally, no one likes doing a lot of work if they don’t see the need. One of our first steps was to get clients on board with the benefits of the new system, giving a purpose to the migration work. We framed these benefits in terms of reducing/eliminating pain points that clients had previously experienced with our platform. For example, the new system would give them the ability to search, checkout, and deploy their integrations using standard LinkedIn tooling, instead of using custom mechanisms that required a learning curve. In a few instances, these pain points actually occurred during the migration process, which gave us an opportunity to highlight the benefits that they would experience once the migration was complete. We found that once clients understood the motivation behind the migration, they were much more agreeable to working through the process. Plus, some even got excited about the benefits they would soon receive from the new system! 

Write clear step-by-step instructions
After documenting all of the necessary steps to perform this migration, we used these instructions to migrate a pilot use case ourselves, following only the exact written instructions without considering any of our prior knowledge. This helped ensure that our instructions were sufficiently detailed and easy for anyone to follow. When working across multiple teams, your collaborators don’t have as much knowledge as you do about your specific domain. Documentation explaining the full context makes it easier for them to ramp up, understand what you’re asking of them, and complete the work on their own. As the first few clients performed their migrations, we asked them for feedback on how we could improve the instructions, and ended up adding even more details along with copy/pastable commands, examples, and an FAQ. Eventually, our instructions were clear enough so that many engineers were able to complete the migration without any help from us at all. Documenting every little detail can be painstaking, but enabling self-service pays off in the long run. 

Provide automated tooling wherever possible
For our migration, each client team had to set up a new directory with a specific structure, and then copy several files into a subdirectory for each of their individual use cases. These code changes were almost identical for all clients, and tedious to accomplish with “mkdir” and “cp.” So, we created Python scripts that clients could use to perform this setup/copying. For our larger clients who had 10+ use cases to migrate, this cut 1-2 hours of work down to < 5 minutes. 

In any distributed project, there are often similar tasks that need to be done by many different people and/or tasks that are trivial but time-consuming. Finding all possible opportunities to leverage automation can save a huge amount of cumulative time. For example, saving one hour per engineer in our migration reduced the overall project timeline by three working weeks. Minimizing time spent on monotonous tasks is also good for morale; most engineers would much rather spend their time solving interesting problems than drudging through repetitive labor! 

Make it easy for clients to find help
Having been on the other side of big projects like this, we know it can sometimes be difficult to chase down answers when encountering an issue. We aimed to minimize friction in our clients’ experience by making it easy for them to find support. One support method was a Slack channel specifically dedicated to questions and issues that came up during the migration process. As the project deadline neared, we also set up “workstation” days where clients could sign up for 1:1 support. These were especially useful for live debugging sessions, in which we could quickly work through any issues that came up and ensure the clients left the workstation with functioning code. Dedicated support time and prompt replies help issues get resolved faster and with less frustration. 

Utilize decision frameworks
At LinkedIn, organizationally complex, high impact, and large scale projects operate within the framework of HIs. The HI framework ensures such projects 1) have proven importance and urgency,  2) are built on a high quality technical solution with a clear and specific execution plan,  and 3) have avenues for building alignment with partner teams on roles, responsibilities, priorities, and timelines. By modeling our project within the HI framework during our planning phase, we were able to obtain commitment and buy-in from partner teams that increased confidence in our project’s successful completion. 

Even if such a framework does not exist formally in your organization, prioritizing communication and alignment with partner teams at project onset sets cross-org projects up for success before execution even begins.

Track project progress
Effective tracking can make the difference between a project that finishes on time, and one that never quite makes it to the end. The upfront cost for setting up JIRA and experimenting with different project management methodologies paid off in the long run with increased focus and operating efficiency. Regular status meetings, clear categorization of issues, and utilization of workflows and dashboards on JIRA helped us monitor, visualize, and quantify progress across the 600+ use cases affected by the migration.

When running an initiative with many dependencies, proper tracking helps ensure nothing slips through the cracks. Issues and roadblocks are bound to appear in any project, but effective project management surfaces risks early on, reducing the probability of setbacks significantly impacting the overall project goal. Also, by maintaining consistent and transparent communication with partner teams and stakeholders throughout the process, we built trust and strengthened working relationships with colleagues that continued to pay off well after this particular project was wrapped. 

Using JIRA to track requirements and dependencies allowed us to thoroughly track 600+ dependencies on partner teams. Charts helped visualize overall project status at a glance at any given time during the project period.

Each use case migration in our project required distributed effort from both our team and our partner teams. Comprehensive  project tracking dashboards allowed us to track the status of each use case, so we could easily see which use cases required action from our side, which were waiting on partner teams to move forward, which had recently had progress or updates, and which were complete and required no additional effort.

Conclusion

Although we ran into a few unexpected obstacles and delays, we completed our migration within three quarters and were able to successfully deprecate GaaP’s legacy deployment backend. Throughout this journey, we found each of these strategies imperative to our project’s completion. We run many of these large, cross-functional projects every quarter. With a microservice architecture, it’s inevitable that there will be several initiatives that require coordination among different teams. We received a lot of feedback from our client teams during the migration, including suggested clarifications to make the instructions more clear and how accurate our estimates were. One client even said, “This was one of the smoothest HIs that I've done!”

During our project, we were surprised to find that planning for the migration took almost as much effort as executing it. But initially investing our time into the instructions, automated tooling, and streamlining the process was well worth the time saved for both us and clients during the migration. We found that the more tedious work we eliminated, the happier everyone was. We also found that it was beneficial to keep everyone happy because relationships matter! This project actually helped us build stronger relationships with some of our clients, which have paid off as we’ve continued to work closely. Overall, this project was extremely rewarding, both by eliminating tech debt and by showing us that large, cross-team initiatives can be win-win situations for everyone involved.