Software Engineering teams usually have a very special evolutionary dynamics. Often they start small and stay like that for a while, or better to say, until the solution gains traction and the feature requests start to overflow the team’s capacity.

It is usually this late stage when companies start adding people, but hiring takes time and the teams have to survive. Trying to cope with the load and push for the speed, usually teams start to allocate similar tasks to same people. Of course people working on the same parts of the software are faster than the rest who seldomly contribute on those areas. Speed is a factor of convenience on many perspectives, therefore usually the evolution of these knowledge siloes is tolerated, until it becomes a problem. An engineer goes on vacation, every change on their silo-part slows down, or halts altogether. Or even worse, an engineer leaves and the whole team falls in chaos as no-one knows the “black box” of the other.

In my two decades in software engineering, I have very often encountered situations of knowledge siloes, in small as well as large companies. Almost always, the intention behind was benign but at the end in one way or another it caused annoyance to everyone.

Knowledge siloes are bad for both individuals and the team. They can be fixed, but it requires a systematic approach and discipline

The role of Engineering Manager in fixing knowledge siloes

Engineering Managers (or Team Leads) are often pushed to focus on delivery as this is their primary responsibility. Very often, the pressure to deliver faster comes from multiple directions. From the desire to achieve the team targets, to business objectives and all sorts of other circumstantial requirements. However, knowledge siloes are a sort of technical debt that haunts the team (and the company) later, therefore needs to be addressed systematically.

As the responsible person for the team, Engineering Manager is also responsible to make sure to create and facilitate the culture of knowledge sharing. Engineers should have the time for knowledge sharing and it is the Engineering Manager who has to make that possible. The team should be enabled and supported to do so. Knowledge sharing should be part of the process and not a handover task, therefore it should be incorporated in the regular delivery flow of the software.

Effective Strategies for Knowledge Sharing

What are the strategies that you as an Engineering Manager can follow to effectively address the challenge of knowledge sharing? Here are some that have proven to work well:

  • Writing comprehensive documentation
  • Conducting thorough PR reviews
  • Holding team presentations for major updates

Writing Comprehensive Documentation

Writing documentation (e.g. on Confluence, Notion, etc.) could be a remedy for saving the knowledge from people’s brains onto a shareable space. Especially if you need to document large concepts such as architecture, complex business decisions etc. Documenting on such central tools also helps with organizing knowledge and long retention. The main drawback about this strategy is that after some time documentation tends to be outdated. Unless a rigorous discipline for updating is applied, this effort can go waisted very quickly. Stale documentation is not trustworthy, therefore no one will read it.

Actionable advice:

  • Document only long living concepts (e.g. high level architecture, business decisions, legal requirements, processes, etc.)
  • Book time in your planning to update the documentation. If something changed that should be updated in the documentation, this should be a written task done following the implementation of the change (do not put somewhere down into your backlog :))

Conducting Thorough PR Reviews

If done properly, I would consider the reviews as one of the most effective ways to share knowledge. It is the live documentation of what the code does. At the same time, the reviewer understands the transition from how it was to how it will be after merging. The disadvantage, if in a hurry (which often is the case) people tend to do the review superficially, not paying too much attention to understand it properly.

Actionable advice:

  • Make it a rule, every change should be PR reviewed
  • Push for small PRs. Human brains cannot cope with too many variables at the same time. It’s difficult to review a PR with 10+ files
  • Let the team feel the responsibility jointly. The reviewer is as responsible of the change as the implementer

Holding Team Presentations for Major Updates

This is one of my favorites, especially if major changes are introduced. Sometimes things cannot get documented so quickly, also not everyone can be involved on every part and every review, therefore you have knowledge leakage. Such team presentations are intended to bring everyone on the same page by presenting the latest developments and changes introduced. At the same time, giving everyone a chance to ask questions and gain more understanding. The downside of this is that it is time-expensive therefore not feasible to do too often.

Actionable advice:

  • Every major change should be followed with a team presentation
  • Even if you have no major updates, make such a presentation at least once a quarter. It serves as a refresher for the team as well as make everyone aware how much you have achieved in that quarter.

My favorite strategy for know-how sharing

All of the above mentioned strategies work well and have their benefits. At the same time, they have a common weak point: human laziness. Humans are lazy by nature (I guess this is a good thing, we need to preserve energy), therefore these practices have a tendency to degrade over time.

The documentation gets outdated as people don’t find time to update it. PR reviews start to get done fast because people start to pay less attention or are in a hurry. Tickets get written fast and in less details. If we can skip a step because we are in a hurry, then we will do it. But, there is this one thing that we cannot skip is, and it is the code that goes to production.

Therefore, my favorite long term strategy has two rules:

  • Code is the documentation
  • Everyone works on all parts of the codebase that they can

Let me get a little deeper on these two concepts.

Code is documentation

The only documentation that does not get outdated is the code that is running on production. The only exception to this would be complex business logic and agreements which can be documented somewhere else and usually they don’t change often therefore less risk of getting outdated.

The code should be written clearly and tested reasonably well. Test scenarios serve also as specifications/requirements documentation. In test cases one sees what the code should do and what should not. From them, most of the code should be explainable. If the team holds on to this principle with discipline and hones the craft of writing well tested code, the knowledge sits in the code base and not only in the brains of individuals.

This kind of documentation, will not only make it easy for people to touch most parts of the codebase, but it will also make the onboarding of new engineers a lot faster and efficient.

Everyone works on all parts of the codebase that they can

The key to spreading knowledge is the necessity for having it. Yes, we can encourage people to learn more and we can support them to do, but our brains are mostly wired to hold the information we deem as absolutely necessary, the rest tends to slip away. If people have to touch different parts of the application, their contextual memory of those parts will be fresh and it will be easier for them to jump from one part to another. Also, this will lead to a more concise implementation style across the application.

I hear you asking, but how can everyone work on every part of the application. The key is in the part “that they can”. Of course we would not expect a frontend engineer work on backend tasks and vice versa (unless you have full stack teams), but they work on all parts of the codebase that falls inside the limits of their specialization. In other words, every backend engineer work on every part of the backend codebase.

Short term vs. Long term

Your actual situation will decisively influence which strategy you will and can follow. As for everything, there is no silver bullet to this problem, but the above mentioned strategies certainly help to achieve knowledge sharing in engineering teams.

If the need is for short term, I would recommend go for quick documentations, reviews and know-how sharing sessions. If you want to play long term, I have seen that my strategy works quite well, but it requires the team to work together at least 3+ months to start seeing any tangible benefits. It requires patience and a lot of stakeholder explanations. At the beginning it will slow down the team, but long term you will go far with this.

If you liked this post, subscribe to receive new posts to your inbox

Leave A Comment