I worked on a thought exercise recently: I wanted to know how much of my technical knowledge about certain things was acquired, well, accidentally. How much knowledge rolling around up there just sort of accidentally hit me through coincidence?

Luck through entropy is an interesting way of learning, for certain – you might envision someone sliding around the floor on funny cautionary platitudes – as if they were roller skates – and that would certainly describe one way that we as human beings learn, but I was focusing more on my experiences of “ramping up” in new roles after having recently changed positions after a long, eight-plus year run at the same company.

I’m talking about knowledge that you get mostly by being in proximity to something, or someone, for a sufficient amount of time. Some refer to this type of knowledge as knowledge that you acquire tacitly. That seems like a fair way to describe it:

Tacit knowledge or implicit knowledge —as opposed to formal, codified or explicit knowledge— is knowledge that is difficult to express or extract, and thus more difficult to transfer to others by means of writing it down or verbalizing it.

Building on that, sometimes the reason knowledge is difficult to express or extract is because it never occurred to anyone to take a moment and write it down. That also coincides with what we commonly refer to as tribal knowledge:

Tribal knowledge is any unwritten information that is not commonly known by others within a company. This term is used most when referencing information that may need to be known by others in order to produce quality products or services.

That’s what provided me with the urgency to come and write about this, because I also realized I’ve been both providing and receiving the short end of the stick when it comes to learning new things in new places, and it doesn’t have to be this way anymore. I discovered that we’re not only failing to set people up for success, we can also be very inadvertently setting them up for, well, not success.

This wasn’t just an exercise to pass away an idle Tuesday, this was a thought exercise that excited me because I’m now shaping a product that I hope will change the way developers on-board to new code dramatically for the better, which brings deficiencies in how we as humans manage the learning process right into my crosshairs. We can do better by our fellow humans, fellow humans! If you’re here for the `tl;dr`, I can offer you this, but I sincerely hope you stick around and read the rest:

Don’t rely on situational circumstances to convey essential knowledge to new hires; make the path deliberate and equally valuable to those that learn on their own, and those that learn best in groups. Present everyone with the same breadth of knowledge so that everyone knows what there is to learn, and let them learn in a way that works best for them.

We can invest more in our future by investing more in the people that are ultimately going to shape it. As we work to build inclusive teams that span the globe in remote-first and remote-friendly organizations, it’s absolutely critical that we better train ourselves on what to capture and when to capture it. Here are some things that you can probably do right now that can have seriously positive long-term effects on how your developers learn.

Why does this matter?

If you put fuel in a vehicle, you’ll probably do so at a station where you connect a nozzle that dispenses fuel to the vehicle’s fuel container. That makes sense, right? You know that the vehicle requires fuel to operate, so you make sure it has plenty in the right place. Gasoline, petrol, car, riding lawnmower – it’s all pretty universal, right? I know, most humans aren’t petrol-drinking riding lawnmowers; I’m getting to that next.

The way that we on-board new developers is often exemplified by a different, slightly more tragic take on that analogy: what if you just poured the fuel all over the top of the vehicle in hopes that it might “sink in” somewhere? That’s sub-optimal, it’s anti-inclusive and it can have very damaging effects on people early-on in their journey with your organization, aside from being a serious fire hazard:

  1. More experienced people might recognize this pattern, and how they struggled in the past just to bring themselves up to the same level of knowledge and context as others that had been with the company longer. They were hoping this time would be different, and their on-boarding experience became a wasted opportunity to really develop early engagement.
  2. Some employees might blame themselves for taking longer to get up to speed as others, when in fact it was just simple luck. One of their peers might have had the good fortune of over-hearing a conversation where critical information was discussed, which prompted them to ask more about it and become productive sooner.

It’s not that any of this is intentional; we want others to succeed and we work hard to try and set them up for success! But, we can really shoot ourselves in the foot by not recognizing that people are at their most vulnerable when they’re just starting out, because a lack of consideration can feel very, very personal. This is especially true for folks that often see their needs go ignored.

While it’s true that imposter syndrome is a real thing, I feel like we blame it (and by extension, the new hire) way too much for what’s ultimately our fault: not capturing key information. To fix it, we need to think about some changes to the way we define our engineering culture.

What can be done about it?

This isn’t unlike any other thing you suddenly learned could be going much better than it’s currently going, and the answer depends on a lot of things. If you’re in a position to make change happen and manage that change, you can try any number of things that I talk about below. If you’re not in that position, perhaps consider sharing this with someone who is.

I’m also figuring this out as I go, because while software can’t force us to get better at things, it can be designed in a way that results in better patterns being followed naturally. That’s constantly at the front of our minds as we think about Swimm’s features and goals as a product.

Either way, if you can identify with any of the things below – you can take steps to improve what your position on learning says about your company to the folks that join it. This also isn’t gloom and doom, there are amazing companies out there and they stay amazing because they never stop iterating on critical processes, like learning and onboarding.

1. Keep up-to-date documentation full of examples with a knowledge catalog

We, uh, have a product that can help you with that, but that’s not the main point – the point is that you have something that you can rely on to help new folks get up to speed. A great way to help people find the knowledge that they need is to organize it procedurally, as it would relate to common tasks that they’ll need to undertake and accomplish.

How do you set up your local build environment? How do you add a new configuration value to the site setting database? How do you debug the data-broker service that uses so much RAM that it melts Minikube? Don’t stop there, also think about things like “How do I get approval to buy new software?”

Work is where people go pretty much exclusively to do stuff. That’s why we call it work. Anticipate as many needs as you can, build an index of it, and let people dive in as deep or shallow as they need to in order to get their work done. Trust them to know how to learn it if they know everything that’s available.

2. Stop knowledge leaks with an offboarding plan

A question I like to ask on exit interviews is: “On a scale of 1 to 10, how knowledgeable of our code would you rate yourself? … (they answer X) … Fantastic. What’s something someone rating themselves X-1 might learn from you? What could you learn from someone rating themselves X+1?

This is a great question even outside of engineering because it will often turn up uncommon knowledge that the person holds, and point to uncommon knowledge that others might hold, which you want to be sure is documented. Aside from that, communicate that answers will be given to the person’s backfill, and encourage them to include everything they can think of, even if it’s obscure or soon to be moot.

3. Foster a “documentarian” culture

We’re life-long learners. We see the opportunity to help and teach others as an enormous privilege, and we always look for and take opportunities to do this even better than the last time. We never worry about others getting irritated when we ask to pause for a moment so we can get ideas into a document, because we know that those around us see the value in it too.

We know the future depends on us being as generous as possible with what we know to day, and this can be especially important to our future selves! Make sure it’s always okay to open a document and make knowledge available.

4. Define a firm demarcation point where things must exist in writing

This one is super, super important and is an example of being deliberately inclusive.

You want a collaborative culture where people feel able to grab someone to brainstorm with and carve out an idea. You’d be worried that any kind of gate-keeping around that might stifle creativity. You’d be correct on both counts – but at some point the maximum size of an ‘in crowd’ has to be defined before the idea must exist in a document where people can be alerted to the fact that it exists.

Set guidelines that once a possible initiative has more than two people working on it, that it must have a wiki page of some sort, or a mention in chat with a link to the brainstorming document (even if you are clear that the idea isn’t ready for a bunch of cooks yet).

The sooner you capture things, the better, and the exercise of getting it down on “paper” can actually be helpful to the creative process. Not only does this jumpstart the documentation process for the benefit of those yet to come, it makes sure that people feel deliberately included by removing the chance that the might feel deliberately excluded.

5. Use tools like “Officevibe” to see how things are going

I have no affiliation with any office-tool software, Officevibe is just one that I’m familiar with.

SAAS tools to craft surveys that can also tie into your HR system are springing up everywhere, and they are usually excellent at helping you write great surveys that ask questions in common language without projecting bias. They are also excellent at helping you decide what looks like a yes/no, or might be better off as a slider between “strongly agree” and “strongly disagree.”

Use these tools to find out if people actually trust your documentation to help them get their jobs done, and make sure you capture as much as you can about the onboarding experience throughout the (almost year) that it can sometimes take.

6. Establish a real mentorship program

Onboarding isn’t a time-boxed thing that magically goes away when it approaches a deadline – it can take anywhere from six months to a year, or even longer. Your processes need to be ready for that, and they can manifest quite brilliantly in a proper mentorship program.

Randomly picking-and-pairing people is usually a bad idea. Being a subject matter expert (SME) doesn’t automatically make you a good candidate to be a mentor, and many mentors lack some really important skills to be great mentors. A good start is offering actual mentorship training to those that will be helping new hires get up to speed, and making sure that you work on building a succession of good mentors for new hires to come through over time – don’t put it all on one person’s shoulder.


Wrapping things up, the most important things are to admit that there’s room for improvement, then consistently and deliberately look to identify ways to make those improvements as you create and iterate on your onboarding processes. If you do that, you’ll see attrition and disengagement fall, have happier developers, and see the talent that was so hard to win stick around.

New to Swimm? Sign up for a 1:1 demo today.