Glossary
By the Glue Team
Developer onboarding is the process of integrating a new engineer into a team and enabling them to become productive. Effective onboarding reduces time-to-productivity, improves retention, and sets new developers up for long-term success. Poor onboarding creates frustration, mistakes, and often leads to early departure.
Developer onboarding encompasses:
Good onboarding gets new developers from "I don't know anything" to "I can contribute meaningfully" in days or weeks. Poor onboarding stretches this to months, during which the new developer is frustrated and the team is interrupted.
Onboarding quality has multiplier effects:
Time to Productivity: A well-onboarded developer becomes productive in 1-2 weeks. Poorly onboarded developers take 2-3 months. That's a 6-12 week difference in time before they're contributing meaningfully. For a team of five, that's lost years of productive capacity over time.
Hiring Velocity: If onboarding is painful, you can't scale hiring. You can only add one new developer at a time because each one requires intensive mentoring. Good onboarding lets you hire multiple people without proportionally increasing disruption to existing staff.
Retention: Bad onboarding experiences are a leading cause of early departure. A new developer who spends their first week confused and frustrated leaves. Even if they don't leave immediately, their experience shapes long-term engagement. Great first experiences build loyalty.
Quality: New developers who understand the system make fewer mistakes. Rushed onboarding leads to bugs, rework, and technical debt accumulated by people who didn't understand implications of their decisions.
Knowledge Distribution: Onboarding is an opportunity to distribute knowledge. When the team explains systems to new developers, it forces explicit articulation. Implicit knowledge becomes explicit. This benefits everyone.
Team Morale: Mentoring new developers is energizing for experienced developers. It reminds them what they've built. It's also exhausting when done informally and constantly. Structured onboarding makes mentoring sustainable.
Multiple things need to work together:
Documentation: Setup guides, architecture documents, decision records. Documentation should exist before the new person arrives. Reading docs is faster than asking questions. Docs scale; one-on-one explanations don't.
Structured Plan: Know what the new developer should learn in week one, week two, week three. Have explicit milestones: first commit, first review, first feature, independent operation. This structure helps both the new developer and mentors.
Mentorship Assignment: One person should be primary mentor. Not "everyone can help" (leads to no one helping consistently). A designated mentor ensures the new person has someone to ask anything.
Pair Programming: Initial development tasks are easier with a mentor watching. This is intensive but pays off—the new developer learns faster and makes fewer mistakes.
Existing-Code Reviews: Have new developers review existing code before writing new code. This teaches patterns and exposes them to the codebase.
Accessible Codebase: This is less about onboarding process and more about code quality. A well-structured, well-tested, well-documented codebase onboards faster than an equivalent team with messy code. This is where tools like Glue help—when the codebase is intelligible, onboarding accelerates.
Integration Activities: Non-work activities help team formation. Lunch, coffee chats, casual conversations. Not just meetings.
Feedback Loops: Check in frequently. After day one, week one, week two. Ask "What's confusing?" and fix confusion sources. What was hard to find? Document it. What took longer than expected? Automate it.
Most teams should have:
Lack of Documentation: The most common problem. Team knows the system, so they don't write it down. New person arrives and everything is oral. Mentors are bottlenecked answering the same questions.
No Structured Plan: "Go figure out the codebase." New people don't know where to start. They optimize for random exploration instead of systematic learning. Takes longer.
Outdated Documentation: Docs exist but are wrong. This is worse than no docs—it's actively misleading. New developers follow docs, hit dead ends, lose trust in documentation.
Mentorship by Interruption: No designated mentor. New developers interrupt whoever's available. Everyone is context-switched. Learning is inefficient.
Thrown into Deep End: First task is a critical system with high complexity and no support. New developer struggles. Makes mistakes. Gets demoralized.
Unclear Expectations: New developer doesn't know what success looks like. Is day five too early to expect first contribution? Should they be independent by week two? Ambiguity causes anxiety.
Onboarding improvement is high-leverage work:
Document Architecture: Write down how systems work. Why decisions were made. This is done once and benefits everyone.
Create Setup Scripts: Automate environment setup. What takes two hours manually should take five minutes with a script.
Write First-Task Guide: Have a well-documented, non-critical first task that every new developer does. This teaches patterns and builds confidence.
Assign Mentors Explicitly: Make mentorship a responsibility, not a burden. Give mentors time. They should review the new person's code in priority.
Check in Frequently: Daily check-ins in first week, several per week in month two. Address confusion immediately.
Iterate Based on Feedback: Ask every new developer "What made onboarding harder than it needed to be?" Fix those things.
Glue accelerates developer onboarding by making codebase knowledge accessible. New developers can ask "What does this service do?" or "Where is payment logic implemented?" and get answers immediately instead of searching or asking. This self-service knowledge reduces onboarding time significantly.
"Good onboarding requires a dedicated person." Partly false. Yes, good onboarding takes time. But it doesn't require a dedicated full-time person. Distributed mentorship works if structured well.
"Onboarding ends after one month." False. True onboarding is three-six months. Month one is basics. Months 2-3 are building depth. Months 3-6 are moving from "can do the job" to "understands the job well."
"Smart developers can onboard themselves." Partly true. Smart developers can overcome poor onboarding, but they're slower than they need to be. Good onboarding makes even brilliant people productive faster.
Knowledge Silos: Onboarding is hindered by knowledge silos. If all knowledge is in one person's head, onboarding requires that person's constant attention.
Code Health: Well-structured, tested code onboards faster because it's easier to understand.
Bus Factor: Good onboarding distributes knowledge, increasing bus factor.
Q: How long should onboarding take? A: Full productivity varies. Simple, well-documented systems: 1-2 weeks. Complex systems: 4-6 weeks. Achieving deep expertise: 3-6 months. Different roles also differ—backend engineers might take longer on a distributed system, frontend engineers shorter in a simple UI codebase.
Q: Should all new developers follow the same onboarding path? A: Mostly. Basic knowledge is universal. But senior developers might move faster. Engineers from different backgrounds (backend vs. frontend) might need different paths. Have a core path but allow customization based on role and background.
Q: How do you measure onboarding success? A: Track time to first contribution, time to first feature, time to independent operation. Also survey new developers—did they feel supported? Did documentation help? Were mentors available? Both quantitative (time) and qualitative (experience) matter.
Keep reading
