Jacob Kaplan-Moss


You should maintain a transition file

In this post, I’m going to try to convince you to adopt a new practice: maintaining a transition file. I’m aware this is going to be a hard sell: we’ve all got lots to do, and I’m asking you to add another task to your workload. It’s not a huge amount of work, but it’s not trivial — several hours per quarter, something like that. And it’ll likely be completely voluntary: your boss won’t ask you to do this (though, they should…).

What’s a transition file?

It’s a document that you prepare for whoever ends up succeeding you in your role. It should contain all the information you’d want them to know to ensure as smooth a transition as possible. Done right, the document should help them step into your role with a minimum of disruption.

Ideally, you’ll have the opportunity to brief your successor directly, so a transition file can serve as a shortcut to those conversations, or as an outline of things to talk about. But that isn’t always possible: you might get fired or laid off, you might leave for another job without a clear successor named before your last day, you might have to take sudden medical leave, etc. Situations like that will be disruptive, it’s unavoidable, but a transition file will help minimize that disruption.

Why should you maintain a transition file?

I’m on record that you don’t owe your employer much in the way of “loyalty”, but I do believe in a certain level of obligation to your colleagues. Departures are disruptive – especially the kind of really sudden ones that would necessitate a written transition file. Helping your now-former co-workers have an easier time of it seems worth the effort, to me.

More broadly, I believe that succession planning is an aspect of professionalism. Showing up and doing the work is the minimum bar, but doing your job well involves longer-term strategic thinking, which extends to thinking about what’s going to happen when you move on.

Finally, this is also a self-serving practice. Your colleagues will remember how your time working with them ended. If you leave a mess of undocumented processes and procedures that they have to scramble to figure out, their lasting memory of working with you will be that mess you left behind. But if, on the other hand, you leave in a way that feels smooth and planned, they’ll find that impressive. The tech industry can feel weirdly small sometimes; you never know when you’ll run into your colleagues again. Being someone they generally want to work with again is always a good thing.

What belongs in a transition file?

  1. Information about each person you’re managing, mentoring, sponsoring, or in any way involved in their career development

    This is the most important part of the transition file: the parts that help minimize disruption to the people you’re involved in leading (in any capacity). This mostly applies to managers – minimizing disruption to your direct reports shouldn’t be optional. (Managers only need to do this for people who report directly to them; no skip-levels.)

    But it also applies to senior engineers who are mentoring someone more junior, executives who are sponsoring someone, people overseeing interns, etc. If you’re involved in someone’s career, you owe it to them to try to minimize the impact of your leaving on their career.

    For each person, you should write down:

    • Their most recent performance review (managers only).
    • Your notes towards what you expect to be in their next performance review (managers only) (I actually use my transition file as a holding ground for notes towards my next performance review, so this section serves double duty.).
    • Any recent feedback you’ve given them.
    • A summary of their strengths and weaknesses.
    • A summary of their career goals, as you understand them.
    • The main areas of growth you’ve been working on with them, and what you’ve been doing together to work on those areas.
    • Any other important context you think a new manager/mentor/sponsor should know.

    This is, essentially, a written version of a manager handoff – the passing-of-context that you’d do in person when someone switches managers.

  2. A list of your ongoing operational responsibilities

    Almost everyone has “keep the lights on”-style responsibilities: things they do regularly that keep the processes of the team moving forward. These are things like:

    • running a weekly planning meeting
    • grooming the issue backlog
    • triaging incoming bug bounty reports
    • sitting in on the weekly sales call so you can summarize upcoming deals for your team
    • representing your team in a community-of-practice
    • … and so on …

    These may or may not be included in your job description, but they are things that you do regularly that are important to the team’s smooth functioning.

    Like all of this document, don’t exhaust yourself. Aim to write down the major ones; if you leave a few out, that’s ok. A rough heuristic for what to include is: imagine you were leaving for vacation for two weeks1. What tasks would you need to be covered while you were gone? Those are the things to write down.

  3. A section for every active project.

    The definition of “project” is a bit fuzzy. You shouldn’t be spending a huge amount of time maintaining this file, so that puts a bit of a natural limit on what you can include. A good heuristic is to include any project that’s going to continue until you update your file next quarter. Anything smaller than that you can probably leave out, or mention very briefly.

    For each project, you should write down:

    • a brief outline of the key goals or outcomes of the project
    • the major milestones and/or deadlines for the project
    • a list of all the important players: team members, executive sponsors, that one person from Sales with a massive deal riding on the outcome of the project, etc.
    • a summary of any major risks or challenges you’re facing
    • your overall assessment of the project’s status (on track? behind? on track but risky?) and the reasons you think are behind that status

    If you’re working in an organization with strong project management discipline, much of this might already be written down somewhere else. If so, that’s great! Simply link to those other resources. But my experience is that most organizations don’t have this discipline, or even if they do there are one or two projects that are “on the side” and not very well tracked. So, I recommend doing this section even if your organization has a good project tracker. You’ll probably find there’s some extra important information or context not in the official tool.


Finally, a handful of notes on the practice and logistics of maintaining this file:

  • This document should live in a shared location, e.g. Google Drive, Notion, GitHub, etc. If you’re laid off, your work computer might get remotely wiped out before you have a chance to copy off this document. Keeping it in the cloud ensures that your successor can access it given your instructions.

  • It should be private. I don’t suggest sharing it with your manager, and definitely don’t share it with your peers or reports. You want to feel free to keep it unvarnished and unpolished, and thinking about an audience will get in the way of keeping it updated.

  • Update it regularly. Every 2-3 months feels like a good cadence to me. That’s frequent enough that it’s not too out of date at any given point but spaced far enough apart to not require a ton of time.

  • Keep it rough and high-level. You don’t need to be exhaustive, and you shouldn’t spend a huge amount of time documenting every single thing. Don’t waste time documenting work that’ll be done by the time your next update cadence rolls around.

  • Make sure to schedule the work. Use whatever mechanism you normally use to keep track of regular, ongoing tasks like this. I block time on my calendar (2 hours, every 3 months), but that’s how my brain works. As long as you explicitly schedule this as a task, rather than “oh I’ll do it when I remember”, that works for me.

I hope I’ve convinced you to maintain a transition file. If you have any questions or comments, please feel free to reach out. I’d love to hear how it works for you.

  1. If you can’t imagine taking a vacation that long, something’s pretty unhealthy about your team. You should talk to your manager about that, or think about finding a new job that believes in redundancy. ↩︎