A few months ago I wrote Learning and Reviewing System Internals - Tactics and Psychology. One thing I touched on was how it is necessary to create a mental model in order to grok a codebase, or learn how a complex system works. The mental model gets developed piece by piece, using a layer of abstractions.
Today I am also writing about mental models and abstractions, but from the perspective of team leaders, and senior engineers, and their role in onboarding new team members. In this context, the team lead and senior engineers are teachers and how effective they are has a material impact on the success of the team. However, there are real challenges and leaders can fail without being aware of it, with potentially poor outcomes if left unaddressed.
The map, the landmarks for navigation, the mental model
How does one teach an engineer about how a complex system works? You arm them with a high quality mental model, one that gets progressively more complex as they peel back the layers.
The mental model can be documentation, design docs, diagrams, or even an accompanying formal model. Often complex subsystems can be documented separately, assuming a prior understanding of the wider system.
Armed with the right model, the engineer becomes empowered; free to explore the rabbit holes without getting lost. Do you learn English from a dictionary? Does anyone learn a new system by starting at the reference manual? No (well except for my brother maybe). Most of us find blogs and tutorials, and we try to build this simplified model of the thing we wish to learn. Armed with that model we start kicking the tires, writing some code. We uncover specific problems and start consulting the reference pages. We will keep coming back to the mental model, that map of the main streets and visible monuments. Once we have our bearings we can dive back into the narrow winding alleys again.
The cost of failure
The harder you make it for the engineer to go through this process, the harder it will be and the longer it will take. The engineer may never become aware of some key insights or ever get a good handle on the lower level details that can be key to being an effective contributor. It may even cause the engineer to fail and leave. It is the job of the teacher (either team lead or the team as a whole) to make this process as clear and easily navigable as possible.
Failure to prioritize this learning as part of team onboarding can have huge negative consequences that last for months if not longer. One of the most important roles of a team leader is to make this learning process as effective as possible.
I also believe the same applies to open source projects where sometimes documentation, especially internals documentation or high quality code comments are not always prioritized.
The teacher’s nemesis — The Curse of Knowledge
But this is where the curse of knowledge comes in. The curse of knowledge is our own blindness as experts regarding the difficulty of learning something and the complexity of concepts we have internalized fully.
There is a well-known quote from CS Lewis that explains this phenomenon:
“I write for the unlearned about things in which I am unlearned myself. If an excuse is needed (and perhaps it is) for writing such a book, my excuse would be something like this. It often happens that two schoolboys can solve difficulties in their work for one another better than the master can. When you took the problem to a master, as we all remember, he was very likely to explain what you understood already, to add a great deal of information which you didn’t want, and say nothing at all about the thing that was puzzling you. I have watched this from both sides of the net; for when, as a teacher myself, I have tried to answer questions brought me by pupils, I have sometimes, after a minute, seen that expression settle down on their faces which assured me that they were suffering exactly the same frustration which I had suffered from my own teachers. The fellow-pupil can help more than the master because he knows less. The difficulty we want him to explain is one he has recently met. The expert met it so long ago that he has forgotten. He sees the whole subject, by now, in such a different light that he cannot conceive what is really troubling the pupil; he sees a dozen other difficulties which ought to be troubling him but aren’t.” CS Lewis
So what can the expert, the teacher do?
Awareness and empathy go a long way.
Awareness that your carefully constructed mental model of documentation and diagrams may still confound the learner in unpredictable ways. Empathy to care enough to help them through it, giving them the benefit of the doubt.
You clearly see the whole elephant in all its glory, but the learner may be holding the trunk in the dark thinking they have a leg. The worst thing you can do as an expert is act as if any given fact about a system is “obvious”. You as an expert that has fully internalized everything is a poor judge of what is obvious and what is not.
So write down your mental models early on, and constantly get feedback and contributions to those models from new members of your team or project. The expert is probably not the right judge to say whether the documentation and getting started experience is clear. It’s not the expert’s fault, it’s the blind spot caused by the curse of knowledge.