Introduction

What does world-class software engineering onboarding look like?

In this book, we'll explore how to apply product development best practices and insights from the learning sciences to create excellent software engineering onboarding experiences.

Onboarding is a product

A product delivers value by solving problems.

Onboarding delivers value to new hires by giving them a clear path to go from outsider to insider. It delivers value to the team by preparing the new hire to contribute while minimizing negative impact.

Treat engineering onboarding like a product, use metrics, user research, and iteration to improve.

Treating onboarding as product means focusing on delivering value to onboarding users by deeply understanding their problems, needs, and context, then designing solutions to solve their problems and satisfy their needs effectively in their context.

User-centric

Starts with understanding the user’s goals, pain points, and context—not just building what’s asked, but what’s needed.

Onboarding is a process that transforms an outsider into an insider of a particular group.

Your user, the person being onboarded, went through a hard and stressfull hiring process, they showed up their first day hungry to prove that you made the right choice in hiring them. They don't really know anyone and they have just a faint idea of what success looks like for their first few months in the company. They don't know much about the internals of your software systems and proceess, and they still don't have access to your code repositories.

Outcome-focused

Prioritizes impact (solving a problem or improving a metric) over just output (shipping features).

Systems-aware

Balances user needs, business goals, technical feasibility, and long-term scalability.

Prioritization-driven

Applies judgment to what not to build just as much as what to build—focusing effort on the highest-leverage problems.

Iterative

Uses experimentation, feedback, and data to guide decisions and improve continuously.

In this book, we will focus on the onboarding of Software Engineers into an Engineering group. As most topics around Software, Engineering Onboarding is full of tradeoffs.

Time: Should the onboard be 0 days long (here's a laptop, this is your team, good luck!) or a more structured 90 day long process?

Focus: Should onboardees be sequestered and only focus on onboarding or should the process be integrated with their regular work?

Breadth: Do we teach about all the systems we have or should we focus on teaching the systems that they are more likely to interact?

Depth: Do we give general overviews or we go deep into all of the topics?

Onboarding is also a sociotechnical system.

It includes understanding the company's culture and goals, its engineering culture, idioms, procedures, and best practices.

150 Engineers

Before reaching approximately 150 Engineers, onboarding looks a lot like an apprenticeship. A more tenured Engineered is paired with the new person and run a hypercustomized onboarding process similar to a master blacksmith teaching their apprentice. From the perspective of the learner this is very efficient as they are taught exactly what they need close to when they need it and they have access to a fast learning feedback loop. It can also be very positive for learning the company culture and can lead to a professional closeness that continues long beyond onboarding. From the perspective of the instructor is has a non-negligeble cost. All the time they spend teaching the new person is time they are not working on other team goals. With a focus on the near future the cost is well worth it as it leads to another person supporting the goals of the team.

Things change at some point after 150 Engineers, especially when the company is hiring fast. The cost of having say 1/3 of the Engineering group engaged in onboarding starts to look scary. 150 is also Dunbar's number, an estimation of the limit of the number of people a person can maintain stable social relationships with. After 150 you see more subcultures emerge in the organization and there is generally less uniformify in procedures and experiences at the company. So a person being onboarded on team A could have a very diferent onboarding experience than a person being onboarded on team B.

A combination of the lack of uniformity of the thoughput impact leads to apetite in the organization for professionalizing onboarding and centralizing it in one team. If you are reading this, chances are you are part of such a team.

Design

Leverage techniques like guided interaction and worked examples to improve knowledge retention and engagement.

Instructionism and the "banking" concept of education

There is a good chance that the educational experience you received is based on instructionism. Instructionism was designed for the industrialized economy of the early 1900's and focused on ensuring that students become compliant and efficient workers. The are no major problems with optimizing for efficiency, but instructionism's focus on workers that are compliant can create problems. (VUCA, Creativity, etc...)

Paulo Freire, has an interesting analogy that can help you understand instructionist. He talks about the "banking" concept of education where knowledge is "deposited" in the learner's head like money in a bank account

"ninguém educa ninguém, como tampouco ninguém se educa a si mesmo: os homens se educam em comunhão, mediatizados pelo mundo."

"Estes, em lugar de serem recipientes dóceis de depósitos, são agora investigadores críticos, em diálogo com o educador, investigador crítico, também."

"A educação autêntica, ... não se faz de A para B ou de A sobre B, mas de A com B"

Basic facts about learning that works

• It isn't enough to learn facts and procedures, you need to know in which situations to apply them and how to modify them as needed depending on the situation.
• Connected learning: complex bundle of knowledge, not a simple list of isolated facts
• Focus on learning AND teaching. Students don't learn by simply getting better teaching. they need to actively participate in their learning process
• Learning env. create safe spaces for experimentation
• Groups and context
• Build on prior knowledge
• Reflection: express their developing knowledge. conversation or creating artifacts

When can I consider onboarding done?

“onboarding isn’t a single moment, or a single feature, or a single flow. It’s a process that connects many activities, over time, to bridge the gap between trying a new product and becoming a core user of it. Tutorials, videos, setup flows, slideshows, and signup flows may all be a part of that journey, but none alone are the journey.” -- Krystal Higgins¹

It depends on your goals, but people learn at different speeds and at a large company they have very different needs. In general you need to draw a line in the sand and declare it done. But in some sense it is never really done. There is always one more thing to learn.

Measuring Learner Satisfaction

Holistic Learning Experiences

1. "Start with the performance problem"
2. "Determine if learning can help"
3. "Clarify what success looks like"
4. "Determine learners' needs"

Authentic Learning Tasks

"An authentic learning task is a task as it exists in real life"

"you need to learn the main 'complex skill' in an integrated manner"

"Complex learning 'involves integrating knowledge, skills, and attitudes; coordinating qualitatively different constituent skills, and usually transferring what's learning... in training settings to ... work setting"

• skill
• knowledge
• attitude

Zone of Proximal Development

"we need to provide the appropriate level of guidance and support to help the learner complete the learning tasks at each 'complexity' level"

Direct instruction model

• "introduction/review: set the stage for learning"
• "development: model the expected learning outcomes by providing clear explanations and examples"
• "guided practice: Monitor and engage pupils with assigned learning tasks"
• "closure: bring the lesson to a conclusion by highlighting what was covered"
• "independent practice: provide learning tasks that are independent of teacher assistance"
• "evaluation: assess progress"

Feedback

• "The goals (Where am I going?)"
• "Current performance (How am I doing?)"
• "Future performance (Where to next?)"

"(feed up, back and forward)"

1. Task level
2. Process level
3. Self-regulation level
4. Self level

"only telling learners that they're doing something wrong can be detrimental if they don't understand why they're doing it wrong and what to change to do it better"

• corrective feedback (what)
• directive feedback (how)
• epistemic feedback (why)

novice learners benefit more when feedback is directive. advanced learners benefit more when feedback is epistemic.

Worked examples

"A worked example typically illustrates a principle or pattern, which helps learners to abstract the important/relevant information to map to similar or even different problems. It helps them go from the surface structure to the deep structure of problems, focusing on structural aspects of problems to derive the underlying concept common to the examples."

Spaced learning

"The effectiveness of spaced learning comes down to this: tackling learning in various short sessions works better than learning than learning that same thing in one long session"

Retrieval practice

"They found that testing repeatedly works better than just one-time testing"

"Production (coming up with the answers yourself works better than recognizing answers)"

Interleaving

"Interleaving is basically a method to space practice"

"When we design related but different learning activities we achieve several good things, For starters, we add a layer where learners need to decide which strategy they need to choose... We help learners figure out what distinguishing elements there are on which they need to base their choice approach..."

Self-directed learning

"SDL is the process where someone takes the initiative to diagnose their own learning needs, formulate their learning goals, identify learning tasks to be carried out to support their learning, and perform those tasks"

"The learner doesn't necessarily always start with determining a learning need. They might just try to complete a work task, run into problems and need to find a solution"

Personal learning network

"the network of people a self-directed learning connects with for the specific purpose of supporting their learning"

• consume
• create
• connect
• contribute

Productivity

Effective onboarding leads to faster ramp-up, better developer experience, and higher retention rates.

Inclusivity

Design onboarding processes that support engineers of all backgrounds and experience levels.

References

• Neelen, M., & Kirschner, P. A. (2020). Evidence-Informed Learning Design: Creating Training to Improve Performance. Kogan Page.
• Sawyer, R. K. (2022). The Cambridge Handbook of the Learning Sciences. Cambridge University Press.
• Freire, P. (1974). Pedagogia do Oprimido. Paz & Terra.