How to make knowledge transfer work better

There is no "just"

Disclaimer: the idea of this post came from someone's comment on social media some years ago and is not entirely mine. Unfortunately I am not able to recover the original comment today.

First, a short example. During one of my first lessons on horseback riding, I'm just sitting there and thinking, oh, the horse MOVES, it was so nice when it was just standing still, will I fall accidentally?

We walk around the arena and the coach says "just walk closer to the fence". But, I am very new to all this. I do not know how you translate "just move this way" to actual commands to the horse in terms of its API, that is, through the bridle and my legs (you are supposed to use the inside leg and push in a certain way).

Knowledge transfer occurs when someone is trying to learn the ways of a project, perhaps with the added complexity of entirely new (for them) technological stacks. It is not often that the new things are intuitively perceivable. Some undocumented details from that rushed initial phase or legacy core, a non-straightforward CI/CD setups, or simply a new cloud platform. There are always missing parts of the picture. And that's ok - it doesn't matter who you are now, as long as you can learn at a good enough speed. And the word "just" is the last thing we want to hear in such a situation because often you need to go to severe, almost painful cognitive fiction trying to figure out what "just" means - ask more questions, google around, et cetera. And this is all for just one step! Probably after that step, there will be a hundred of other steps, which, in this way, will take considerable time, burn your brain and demotivate you massively. Not only are you in pain for trying to work things out, but you also are not at your best speed - a lot of energy dissipates into figuring out the vague suggestions, so you are stalled in your tracks and actually look worse than you are. Additionally, the mood in the team ends up tense - the new person may have the impression that colleagues do not take collaboration seriously, start to worry that they withhold the knowledge intentionally or whether the situation reflects a frustrating state of the entire company’s work processes.

As a paper in Psychology Today suggests, there is one more issue with “just”:

So, some people may even get deceived by “just”, and this is another reason to be wary of the word in any professional interaction.

So I believe that "just" should never be used in knowledge sharing. Saying something short is convenient for the knowledgeable person themselves. They might feel that the question distracted them from their flow, so they are tempted to get rid of a distraction with the least amount of energy and move on with their tasks. If they give in to the temptation, “just” happens. On the contrary - it should be convenient for the recipient of the knowledge because the knowledge is only useful once it is transferred correctly. Knowledge sharing is an investment in future progress speed-up by adding new collaborators to the team.

What does proper instruction look like?

• How do I do operation X?
• Please make sure you have credentials Y found at the link Z. Once you have them, login using form B and proceed to the link C. Locate your item using search by keywords D. Use the documentation from the cloud provider LINK concerning doing the operation E. In case you are lost, reach the team in the slack channel F. And yes, I actually copied it from a single source G that you are encouraged to update if you find a missing bit.

Even though I call here for spending some more energy on the knowledge transfer, it does not mean we should not be smart about it and transfer small and large chunks of knowledge in the same way. If something takes a lot of explanations and requires many hours or days of work to put it down in writing, I would usually do a screencast that I record. You will be surprised how much knowledge is transferable in such a way for just in 30 minutes of work, and how easy it is to recover it, say, in a year. Precise can be also relatively easy.

Exhaustive knowledge transfer is the way

We all know that unit tests should be self-sufficient, right? Setup, test, tear down; leave no loose ends. The same self-sufficiency should be true about knowledge sharing and documentation. Leaving “mental black holes” in the text defeats the purpose of its very existence. Not only is the word "just" forbidden (unless you refer to a truly trivial matter). Any words like "good", "bad", "sufficient" and the like are open for interpretation and guesswork and only make sense to the writer of documentation because they know the additional context. So it is a duty of the documentation author to provide the same context to the new readers. Say clearly, what “good” and “bad” means in numbers so there is no telepathy required when someone relies on your foundation.

Yes, it is a bit tedious to write a self-sufficient text. But it's also an investment - a written or recorded material can be re-used on those new people many times, saving the precious time and concentration of the experts; that is, if experts have not moved on completely.

So, should we spoon-feed new team members? No, they can take studies themselves too, but under the guidance and in a systematic way. That guidance and system is the duty of the more experienced colleague. I had a pretty good experience telling a person who never worked in Java and never saw my very lengthy code, how to work independently. What I did was first scheduled an hour-long meeting where I drew the building blocks on a whiteboard and showed them how to get the code running and insert breakpoints. Then I show how to trigger incoming API calls and simply assigned homework - to go and trace the calls one by one. They ended up with a short text that perfectly documented the business logic flow. Later, we held another meeting with some additional explanations and questions/answers, and by then they were ready to tackle feature changes.

There is a powerful resistance in the brain that tries to avoid cognitive friction, and it requires a certain amount of discipline to do what has to be done. Yet, the proper documentation is a part of our work and it should be done rigorously, just like the rest.