How to Onboard a New Engineer Onto a Robot Codebase

Onboard a new engineer with a machine they can break and one real change to ship, not a reading list or a tutorial course. Robot code is learned by watching hardware disagree with it, so time spent reading before touching anything is mostly forgotten; whether the stack is ROS 2 or something small like HORUS changes which route works. The exception is safety-critical machinery, where supervised reading comes first. The rest of this post is for a team lead who has three weeks of somebody else's time and no plan beyond pointing at the repository.

The new hire started on Monday and it is now Thursday. They have read the README, which is nine months old and describes a directory that no longer exists. They have asked three questions, and each answer began with a two minute history of why the code is like that. They have not run the robot, because the robot is in the lab and the lab machine has a build that only one person knows how to refresh.

You know what should be happening. They should be fixing something small and real by now. But every small thing you can think of turns out to touch the launch configuration, and the launch configuration is the part nobody has explained since the person who wrote it left. Meanwhile your own week is disappearing into questions, and there is a quiet worry that this is not a documentation problem at all, that the codebase itself is the reason nobody can join it, and that the last two people who joined took a full quarter to become useful without anybody ever asking why.

What is the fastest way to get a new engineer productive on a robot codebase?

Put them in front of something that moves, or something pretending to move, on the first day, and have them ship one small real change by the end of the first week. Everything else is arrangement around that. The reason is specific to robots rather than general advice about learning by doing. A robot codebase is only half a codebase; the other half is a physical machine with its own habits, and the parts that confuse newcomers are almost never the algorithms. They are the sequence in which programs must start, which values are in the wrong units, what happens when a cable is loose, and why the same code behaves differently in the lab and on the test floor. None of that is readable. It is learned by running things and being surprised. A reading week produces somebody who can describe your architecture in a meeting and cannot make the robot do anything, which is the least useful state a new engineer can be in, because it looks like progress from the outside and feels like drowning from the inside.

What does onboarding onto a robot codebase actually involve?

Onboarding means giving somebody enough of a mental model to predict what the machine will do before they run it. That splits into three learnings that people confuse constantly. There is the domain, which is coordinate frames, timing, control and whatever your robot's job involves, and which takes months and is not your codebase's fault. There is the codebase itself, which is where things live and why they are split the way they are. And there is the machine and the loop around it: how to build, how to get software onto hardware, how to see the logs, how to tell whether a run failed for a real reason or because the network was flaky. That third category is invisible to everybody already on the team, which is why it never gets written down and always causes the most pain. The genuinely hard part is not explaining any single item, it is that all three are being learned simultaneously by somebody who cannot yet tell which of the three a given confusion belongs to. Your job is mostly to label that for them.

What are the actual onboarding routes to choose from?

There are seven routes in common use and good teams combine two or three rather than picking one. You can write an architecture tour and hand it over. You can send somebody through an official tutorial curriculum, which is what the ROS 2 material is and is why teams on ROS 2 have an easier first fortnight than everybody else. You can pair them with a senior engineer for a fixed period. You can hand them a small real ticket immediately and support them through it. You can give them a simulator sandbox they are free to break. You can sit them down with recorded runs from real machines and have them explain what happened. Or, when the stack is small enough, you can have them read the whole thing end to end, which is realistic for a codebase built on HORUS, an open-source real-time robotics middleware for Rust, Python and C++ in which all three languages share the same shared-memory ring buffers, so messages between processes on one computer are never serialised; the licence is Apache-2.0, the project is validated in simulation rather than proven across large fleets, and it is not a full ROS replacement, so most teams meet it as one layer inside a larger stack.

How do the onboarding routes compare?

Read the table by finding the row whose last column describes your team and crossing it out, then combine two of what remains, because no single route covers both the code and the machine.

Two or three rows surviving is the intended outcome. The usual working combination is a first real ticket plus somebody named to unblock it, with a simulator underneath when hardware is shared. The row teams over-rate is the architecture tour, which is written for the author's benefit and read once. The row teams under-rate is replaying recorded runs, which is the only route that teaches what your robot actually does rather than what the team believes it does, and it is the closest thing to reading code you did not write with the answers attached.

What does a failed onboarding look like from the inside?

It looks like a polite engineer asking fewer questions each week, and that is the signal to act on. Someone who has stopped asking has not become competent; they have learned that questions cost social capital and are now guessing quietly, which produces changes that pass review because nobody wants to admit they do not fully understand that part either. Other symptoms show up earlier if you watch for them. Their first pull request arrives in week four instead of week one. They keep working on documentation and tooling, because those are the only tasks not blocked on access to something. They can describe your architecture fluently and have never seen the robot move. They ask about the domain when their actual blocker is that the build fails on their laptop and they think everybody else's works. Meanwhile the team reads the silence as either competence or indifference, and both readings are wrong. The failure mode is almost never intelligence, and almost always access: to hardware, to permissions, to a build that runs, and to a person whose calendar has room.

Are you a two-person team, a growing startup, or an established engineering group?

The three should onboard differently, and borrowing a bigger organisation's process is the standard mistake. A two-person team should not write documentation at all; sit together, work on the same thing for two weeks, and accept that the process is a person. The cost is real, because half your engineering capacity is now teaching, and it is still cheaper than writing material for an audience of one. A growing startup hits the actual transition: the third and fourth engineers reveal that everything important was in the founders' heads, and the right move is to write things down as they are asked rather than in advance, because questions from a real newcomer are a far better specification than anything you would invent. An established group has the opposite problem, which is that documentation exists, is extensive, and is partly wrong, and a new engineer cannot tell which parts. There the highest-value work is deleting stale material rather than adding more, since one confidently wrong page costs more days than ten missing ones.

What hardware can the new engineer actually touch?

Whatever they can break without asking permission determines how fast they learn, and this is usually the real bottleneck. If your team has one robot and it is booked for a demo, the new engineer will spend three weeks reading regardless of your plan, and you will conclude they are slow. The options are worth being deliberate about. A dedicated bench robot, even an old one that limps, is the strongest thing you can give somebody, because the learning comes from surprise and surprise needs a machine that is allowed to misbehave. A simulator is the second best and teaches the code loop honestly while teaching very little about cables, timing drift, and the way real sensors degrade. A shared machine with a booking system is workable if the newcomer gets slots that are theirs, and useless if they are always last in the queue. The worst arrangement is a machine they may only touch while supervised, because every experiment then costs two people's time, and they will stop experimenting. Buy the old robot. It is cheaper than the month.

What if you need them contributing within a month?

Choose their first three tasks yourself, in advance, and pick them for what each one teaches rather than for what needs doing. A month is enough for a real contribution only if nobody spends it hunting for a suitable task. Pick a first task with a visible physical result and a single component to change, so the whole build, deploy and observe loop is exercised in one pass and they see the robot respond to something they wrote. Pick a second task in a neighbouring component, so the boundary between the two becomes a thing they have felt rather than been told. Pick a third that requires them to notice something wrong in a recorded run, because that is the skill your team actually needs and the one nobody teaches. Meanwhile remove every non-technical blocker before the first day: accounts, keys, hardware access, group memberships, and whatever certificate the lab door needs. Teams routinely lose the first week of a paid month to permissions, then wonder why the month felt short.

What if the new engineer has never worked on robots before?

Expect the physical layer to be the surprise, not the programming, and plan the first month around that. A capable engineer from web or backend work arrives fluent in things your robotics team is often weaker at, such as testing habits and release discipline, and hits a wall in a place nobody warns them about: the code is correct and the machine still does the wrong thing. The specific shocks are worth naming so they do not read as personal failure. Nothing can be trusted to happen instantly, so timing matters everywhere. State exists in the world and does not reset when you restart the program, so the arm is still holding the part. Failures are physical and mundane, meaning a loose connector outranks any bug they will write. And you cannot simply retry, because a retry moves a real machine. Somebody coming from embedded work has the opposite gap, arriving comfortable with hardware and unfamiliar with a codebase that several people change every day. Name which gap you are dealing with in the first week, because the two need opposite kinds of help.

What do you give up by sending them straight at real work?

You give up a tidy first month, and some of what breaks will be yours. A new engineer working on live code will push something that fails on hardware, will need review time from your strongest people at exactly the moment those people are busy, and will ask questions whose real answer is that the current design is awkward and everybody has stopped noticing. You give up the illusion that your codebase is understandable, which is uncomfortable and useful. You also give up depth in the short term: somebody who ships in week one may still not grasp why the system is split as it is, and that understanding has to be filled in deliberately during the second month or it never arrives. Against that, you get a contributor rather than a student, you get your unwritten knowledge exposed while somebody is around to write it down, and you find out early whether this person will thrive in a job where the machine is the final authority. Most teams find the mess worth it, but it is a genuine cost and it lands on your senior engineers.

When is ROS 2 the better choice?

ROS 2 is the better choice when onboarding speed is a serious constraint on your team, and it is worth saying so plainly. If you hire frequently, the pool of engineers who already know the vocabulary is far larger than for any alternative, and somebody arriving fluent saves you a month per hire. If your new people are junior or new to robotics, a published tutorial curriculum they can work through unsupervised is worth more than anything you would write. If your team is small enough that senior time is the scarce resource, an ecosystem where the answer to a strange error already exists in public is a direct saving on that resource. If interns rotate through, standard tooling means each cohort does not start from nothing, and how long the vocabulary takes to learn is at least a known quantity. HORUS is not the answer in any of those cases, because a compact codebase is quick to read and comes with no course, no forum thread about your exact error, and no candidate who has used it before. That is a real onboarding cost and teams should count it rather than discover it at the third hire.

Will writing more documentation fix onboarding?

No, and here is why: the documentation problem is a symptom, and writing more of it usually makes the symptom worse. Every page written in advance is a guess about what somebody will need, and guesses age faster than code because commands change while ideas do not. The result is a folder of material that is partly right, which is worse than nothing, since a newcomer cannot tell the good pages from the stale ones and will trust the wrong one on their second day. What actually helps is much smaller and harder to schedule. Write down only what a real person asked, on the day they asked it, in the place they looked first. Keep one page that is guaranteed current, covering how to build, how to get software onto a machine, and who to ask when either fails, and delete everything that contradicts it. Where onboarding hurts most is rarely explanation anyway; it is a build that only works on one laptop and access that takes two weeks to arrange. Documentation cannot fix either.

Is onboarding really a people problem rather than a code problem?

Partly, but not the way you think. The people half is real: a named owner with cleared time is the single strongest predictor of a good first month, and no structural improvement compensates for a team that treats questions as interruptions. But the code half is measurable if you look at it honestly, and it shows up as the tasks you cannot give a newcomer. If every small change touches the launch configuration, that is a design fact, not an attitude. If nobody can run one part without starting all of them, the codebase has no small first tasks in it, and your onboarding plan will fail regardless of how welcoming the team is. If the build works on one machine, every new engineer loses a week to that machine's peculiarities. The useful exercise is to write down five tasks a competent stranger could complete alone in their first fortnight. If the list is hard to fill, your onboarding difficulty is structural, and the same edges that block a newcomer are quietly slowing everybody else too.

How do you decide which onboarding route to use?

Decide by naming the specific thing blocking the new engineer this week, because each blocker points to a different route. If they cannot get the software onto a machine, the answer is the build and the access, and no route works until that is solved. If they can run things but do not know where anything is, a short architecture tour pays for itself, provided it is written the week they ask. If they know where things are but not why, pairing is the only route that transfers the reasoning, because the reasoning was never written down. If they can make changes but cannot tell whether a run went well, recorded runs from real machines are the fastest teacher. If the shortage is hardware time, buy or borrow a machine before improving anything else. Work through them in that order, because the later routes are wasted while the earlier blockers stand, and teams routinely commission documentation for somebody whose actual problem is that they have not been added to a group. The same discipline that makes updates to deployed machines survivable makes a codebase joinable, since both depend on a build anybody can reproduce.

Decide by situation rather than by preference:

• If you are two people -> sit together for two weeks, because writing material for an audience of one costs more than teaching.
• If you are hiring your third or fourth engineer -> write answers as they are asked, because a newcomer's questions are the best specification you will get.
• If hardware is booked solid -> give them a simulator and a dedicated old machine, because learning needs something they may break.
• If the new engineer is new to robotics -> a tutorial curriculum plus a physical first ticket, because the shock is the machine and not the code.
• If the original authors have left -> replay recorded runs, because the recordings remember what nobody does.

When two routes survive, weigh them on the five axes of the HORUS Fit Framework: ecosystem size, setup effort, team size fit, deployment target, and licence. Those five say as much about how quickly people can join your stack as about how it runs, since ecosystem size is a hiring question and setup effort is a first-week question. If your team keeps landing on one computer, more than one language, and a codebase small enough that a new engineer can read all of it, star HORUS on GitHub so it is in your list when you start building.