It’s a familiar story: Two weeks before a developer is set to leave a company, it turns out that they are the only person who has worked on a particular application currently deployed in production.
An unlucky developer is selected to sit down with them and go over the ins and outs of a mind-numbing amount of code — the details of which the departing developer has trouble remembering. Then, the student goes back to whatever they were working on before.
When the application suddenly needs attention some months down the line, they have to relearn the application pretty much from scratch.
Ideally, knowledge transfers would look nothing like this. It can be difficult enough to do knowledge transfers of product information, but once you add in architecture and code, doing a knowledge transfer on the technical level can seem all but impossible.
Unfortunately, knowledge transfers can’t be avoided. So Namrata Shah, senior director of software engineering at Avanade, said it’s important to figure out how to handle knowledge transfers well.
“No company is immune to it,” Shah said. “You will always have people leaving your team, you will always have people who are being promoted, you will always have people who don’t want to work on [something] anymore.”
The best way to carry out knowledge transfers can depend on whether applications are developed using the waterfall or agile approach. In waterfall, applications don’t begin development until all design details are locked down, and developers don’t iterate over the code like they do in agile. Shah said that lots of documentation and in-line code commenting is important for waterfall projects.
Start With Good Documentation
There’s an art to creating good documentation. As with all aspects of a successful knowledge transfer, it takes thought and shouldn’t be thrown together at the last minute. And different parts of an application should be documented in different ways.
Shah said she prefers in-line documentation when explaining how the logic in a piece of code works. And for documentation of front-end components and the user interface, it’s better to take screenshots.
“If it’s a workflow,” Shah said, “you need to ensure that you have good flowcharts — Visio diagrams, UML diagrams — to give a good holistic overview.”
Keep it simple. Don’t make a story out of it so that the person on the other side almost dozes off.”
Shah said it’s important to keep the documentation informative but concise, and to always remember that the goal is to make it easier for another developer to understand the application.
“If somebody gave you this document and you are the person who is going to take this [application] over, would you still like it?” she said. “Keep it simple. Don’t make a story out of it so that the person on the other side almost dozes off.”
Shah said documentation can unfortunately be an afterthought for developers, and that a good way of making sure documentation doesn’t get forgotten is by adjusting the definition of when code is done to explicitly include it.
Collaboration Is Often the Best Approach
Agile engineering teams may find that collaborative activities such as pair programming are more effective for knowledge transfers.
“Definitely, I would say being more collaborative and more communicative during knowledge sharing has worked better for us,” said Min Ong, CTO at nate, a startup that facilitates online purchasing.
Developers at nate try to avoid passing on knowledge by doing a “brain dump,” Ong said. “Generally, we found that learning by doing has been better than just over-explaining the whole system.”
Ong said developers learning new systems are given small sections of the code to work on, and that new sprint iterations serve as natural checkpoints for the team to gauge whether the developer is understanding the system or whether additional support might be needed.
At Avanade, developers use a rotation system to ensure that knowledge of a system is shared with multiple people. Instead of having development teams split up applications between members and have each member focus on developing their own pieces, teams are cross-functional and made up of developers with overlapping skill sets.
We found that learning by doing has been better than just over-explaining the whole system.”
During each new sprint, developers are encouraged to work on areas of the project they haven’t worked on yet. That way, by the end of a project, no single developer has developed any one area independently, and everyone knows a little about each part of the application.
This collaborative method prevents knowledge from being concentrated in a single person, but the process can be time-consuming, Shah said. To make it work, the team needs the right mix of developer skill sets.
“You may have the smallest possible team — we’ve had teams of three or four people — but those three or four people had flexible skill sets,” Shah said. “Today, they may be working on .NET code. Tomorrow, they’re suddenly working on HTML5 or Angular.”
Make Sure Your Team Understands Every Application in Production
It can be just as important to do knowledge transfers on projects that are not actively being developed. Sometimes, large companies can have so many applications in production that even the company has trouble keeping track of them.
“I remember this very specific situation with a client,” Shah said, describing a problem with a legacy application that only generates one report at the end of the fiscal year. “For the whole year, nobody looks at the application — nobody even pays attention to it. If you pulled the plug out, nobody would even notice that the application is no longer online.”
When the application eventually ran into an issue, no one had any idea how it worked, much less how to fix it.
As long as it’s a living system in your production, there should be enough documentation — because you never know when someone will wake up from their sleep and ask you a really good question.”
To avoid that kind of situation, Shah recommends doing an application portfolio assessment whenever the number of applications managed by a company gets out of hand. These assessments help companies compile lists of applications currently being maintained, ranking them in order of criticality.
“We try to break it down and give them the lay of their own land,” Shah said about doing portfolio assessments for clients. “As long as it’s a living system in your production, there should be enough documentation — because you never know when someone will wake up from their sleep and ask you a really good question.”
Critical applications are consolidated together as much as possible, and all the “orphaned” applications — those with no current owner — are identified. If a company finds that the application isn’t needed anymore, then the application should be sunsetted.
“We try to reduce the application footprint to a size that an organization can really manage,” Shah said. “We want every application to have an application owner — that’s what we try to achieve, but we might not be able to achieve it every single time.”
