Preserving Technical Knowledge

If you’ve worked for a single company in a tech job for a while you know that there’s a fair bit of turnover in our world. Folks move on to other jobs, new folks come on, people move between technical teams and over into management, etc. Why, chances are you might even have switched jobs yourself a few times!


One way is to have the outgoing person do a bunch of diagrams explaining stuff. To me this doesn’t help a whole lot; these diagrams all end up looking the same: “this box connects to this cloud where things happen, then there are these other boxes”. But it can’t hurt. My advice here is to keep the diagrams simple. Also, do them in a tool that the next system owner knows how to use, otherwise they bitrot. I suspect there are folks who really learn a lot from these diagrams, so if you are one of those, have at it. But they don’t seem to work for me. I wonder if a way to ensure these pictures have meaning is for the outgoing person to point to a connecting line and say “what would happen if this got cut” and the incoming person has to take a crack at it. That’s probably a decent way to learn about things in general – drop a raise “BOOM” in a random place and think/talk through what effect that would have.

Another way is to do face to face interviews where the outgoing person explains the system. I think this is a bit more effective, however, the incoming person has to know something about what’s going on otherwise none of the information makes sense. “We’ve had a longstanding problem with frobnicators not cromulating” doesn’t mean much unless you know why a frobnicator should cromulate. However, this interview method can result in some frank and earnest sharing about system weaknesses that the outgoing person may be embarrassed to write down. Meetings like this have to have some structure, though, otherwise we just end up shooting the breeze for an hour and the knowledge passing doesn’t actually happen.

My preferred way is to work out a shared handover. So Sally has been running the payroll system, she’s leaving, and Fred is getting it. Sally should start redirecting all emails to Fred. If a report fails once or twice a day, Sally can make sure that there’s some kind of alert set up, but Fred has to be the one fixing it. This is a fine opportunity for Sally to say something like “yeah I could never figure out how to get these gizmos to be 100%, but maybe you’ll be able to sort it out”. Humility goes a long way when you’re outgoing; got to set Fred up for success. If there’s some functionality move in progress – the tax calculations are getting extracted to a third party system – then Fred goes to the next status meeting and Sally doesn’t. He’ll be clueless, but then he’ll know he’s clueless, rather than sitting there with glazed eyes while Sally talks shop. Once the meeting is over he can race back to Sally’s desk with a list of questions and now the answers will mean something to him.

The last chapter of Dave Copeland’s excellent book The Senior Software Engineer talks about an outgoing dev’s responsibility to leave a project in capable hands and covers some of this same material: one on one interviews, reviewing current or potential issues, etc. That’s assuming that it’s an amicable departure, but so is everything in this blog post.

Finally, I think it’s helpful if the outgoing person can give the incoming developer a feel for the importance and impact of the job. “You’re the key person for the payroll team”, “you’ll be able to save 200 accountants hours each day”, etc. A little vision goes a long way towards motivating a developer to make a system better.

This post is cross-posted from Tom Copeland’s blog.