busypeoples profile image A. Sharif ・5 min read

When a new person joins a team or company, that person needs to be onboarded in some form or another. Sometimes it’s done explicitly via a handbook and clear guidelines, sometimes it’s informal and unstructured. But some sort of knowledge transfer has to happen to get the person joining the team productive.


There is no general formula that can be applied, as this depends on how a company is organized, how the knowledge is structured and might be organized around specific roles. In smaller company, the process might be more informal due to capacity and time limitations, in larger companies the process is mostly structured and clearly defined.

From the perspective of the new hire, it might not make a difference. That person needs to understand the process, guidelines and needs to understand the tools as well as gain access to these tools. Also, they might need to know the defined rules and how a company or team is organized in general.

These are two different perspectives to keep in mind. The outside and inside perspective. From an insiders perspective everything might seem straight forward. Insiders know the precise work flow, how to organize their work day, know whom to ask for what. Insiders can navigate the environment, a codebase, a wiki or anything else needed to structure a workday. This information is often implicit. The current staff or team understands the current system.

What we often neglect is to reflect on the current status-quo.

Is everything structured?

Is documentation centralized in a central knowledge base?

Or is the information scattered, unclear?

Is there information that needs to be defined explicitly, but not defined because it’s “obvious”?

Often onboarding is just afterthought, and only becomes a matter of interest or important, when someone new is joining a team.

Let’s think more clearly about why thinking about onboarding differently might also help the current team.

Is the minimal requirement to get productive defined and up to date?

This can be anything, from how to setup a printer to how to setup a development environment. Is there a README inside the repository, that describes every step needed to setup the complete environment. Dependent packages, docker, setup the database etc.

It’s important to have this up to date and available, not just having everything working on the current development teams setups.

What if we need to setup a new environment for an existing member?

Are all the required steps defined in a central place or do we need to ask around to figure out how the setup works. Other important information might be things like a team’s definition of done, how reviews are conducted etc.
Actually, anything that clarifies the current workflow.

Identifying complexity

Another benefit that we gain, is that by making how work is organized explicit, we can identify complexities. Sometimes we are used to a complex setup or workflow because we understand how this currently works and avoid simplifying it due it’s informal nature. But there might be some potential gains being overseen. There is potential for improvement that the current team can leverage.

Breaking down Silos

Information is often organized around individuals that know about a specific topic. Making this information explicit helps to avoid silos being built up. Instead of having to find the right person, that might provide us with the required information, anyone could lookup information inside an internal FAQ section or a central wiki or another form of orgnaized information.

Another aspect is that knowledge might get lost at some point, when the person changes the role or company. The knowledge transfer might happen at a late point in time, missing to pass on important information because it might have been forgotten at that specific point in time.

Reflection on the status-quo

Another aspect is that this might help us to reflect on the current status-quo. Sometimes writing things down explicitly enables us to see things in a more clear manner. Things might seem unclear or too complicated to think about, become clear when writing things down. Another opportunity for improving the status-quo for the current team.

Getting new team members productive

This one should be clear, but it can’t be stated enough, how important an onboarding experience is. It sets the tone for the further collaboration. The onboarding experience can’t just consist of showing someone where the kitchen and the printer is.

It must help the person to quickly understand how things are organized, what formal processes are in place, provide access to accounts needed from day one. It might include a code walkthrough or another form of technical onboarding etc. There is lot of informal and formal information and context to know, to efficiently navigate inside a system, even in very small teams. The new person joining can’t know what information is “enough information”, only insiders know this, but very often this information is implicit. Everything seems obvious from an insider perspective.

Central knowledge Base

This has been mentioned a couple times in the previous points, but it’s good to mention this explicitly again. It’s a central knowledge base. It is a living document, that evolves over the time. It evolves with how the company changes and might even be a historical document, enabling us to look at the “diffs”, every time that onboarding documentation has changed. Some companies make there onboarding documents public, enabling people to understand the culture and work flow before even applying. This might even be a recruiting tool if implemented properly.


There is more we could say about the topic. But we can identify some important aspects that we can leverage. It helps to organize and structure the existing environment and is very valuable for everyone joining a team. Everyone likes to become productive quickly.

No one likes to collect the information over a long time range, and finding more information even later in the process. Also it gives people a chance to find their own tempo and pace when being onboarded.

Depending on the person, the process can be shorter and longer but its not dependent on who is currently available to provide assistance, help or information. The onboarding documentation also helps the existing members to onboard the new person joining.

Finally, there might be a lot of work to do, if there is no current documentation. Start with the most important aspects, like a README file inside the repository. Important links inside a wiki or review guidelines. Once we have documented any information, that is required on a daily basis, we might extend the documentation to more general information.

The good thing is that, it will payoff in multiple ways, for existing and future members of your company or team.

Would be interesting to read any feedback, insights and other interesting regarding the topic.

If you have any questions or feedback please leave a comment here or connect via Twitter: A. Sharif


Editor guide