Bringing a new contributor into a project

Why doing this well matters

Someone who spends a week unable to run the project and unsure what to pick up leaves. Not because they're weak, but because they feel useless and unwanted.

On an unpaid team project this bites harder: only interest holds people, and a week of fruitless struggle kills it.

What to prepare before they arrive

Working setup instructions. Verified on a clean machine. Not "it should start" but "it started".

A short description of the intent. What we're building, for whom, what's done, what's next.

A list of starting tasks. Three or four, marked as suitable for a newcomer.

Someone to ask. A specific name. "Ask in the group chat" works worse: it feels awkward there.

Half an hour of preparation saves someone a week.

What the first task should be

Small. One or two evenings. The goal isn't value to the project but that the person travels the whole route: picked it up, built it, submitted it for review, saw their code in the shared version.

Real. Not invented for practice. People feel the difference and invest differently.

Touching something visible. A button, a label, a screen. When the result is visible, a sense of belonging appears immediately.

Not in the hardest place. The calculation engine or the permissions system isn't for week one.

The first week

Day one. Help them get it running. In person, not by linking the instructions. You'll also verify the instructions don't lie.

The first days. Ask how it's going yourself. A newcomer won't write "I'm stuck" — they'll be embarrassed.

The first code review. The easiest place to ruin everything. Review gently, explain the reasons, and be sure to note what was done well. Twenty comments the first time puts people off for a long while.

End of the week. A short conversation: what's unclear, what's in the way, what's next.

What doesn't work

"Read the code, you'll figure it out." They won't. Or rather, they'll take a month instead of three days.

A huge task straight away. "Build the account area" for someone who doesn't understand the project's structure.

Silence. A newcomer reads absent feedback as "I'm doing everything badly".

Missing access. Waiting three days for keys and permissions is routine at companies and unforgivable in a small team.

A side benefit

Onboarding exposes everything wrong with a project: instructions that don't work, incomprehensible names, missing descriptions, odd conventions only you knew about.

It's the most honest health check a project can get. If someone can't get in, the project is in worse shape than you think.

If the newcomer is you

Ask on day two, not in week two. Write down everything unclear and ask in a batch. And fix the setup instructions, since you're the one walking through them — it's the best first change you can make.