Clean Machine to First Change

Ask how long it takes a new developer to get from a fresh laptop to a merged change. You will get an estimate. It will be wrong, and it will be low.

Taking the measurement

Use a genuinely clean machine, or a fresh virtual one. Not a laptop that already has half the toolchain.

Follow the written documentation exactly. Do not use knowledge you have; if the document is wrong, that is the finding.

Time each step and record where you stopped and asked someone.

Stop at the first merged change, not at the first successful build.

Two people should do it separately. The variance between them is informative.

What it usually reveals

Documentation that stopped being true. A version pinned two years ago, a service that moved, a step that is now automatic.

Undocumented prerequisites. The tool everybody has and nobody remembers installing.

Credentials. Access to the package registry, the container registry, the shared cache, the test database. Frequently the single largest delay and almost never in the setup guide.

Sequential waiting. Access requests that take a day each and could have been raised in parallel or in advance.

A first build that takes forty minutes because nothing is cached yet.

The number is usually days, sometimes weeks, where the estimate was hours.

Why it matters beyond new joiners

Everyone re-onboards. A new laptop, a rebuilt machine, a developer returning to a repository they have not touched in six months.

It measures the fragility of the whole setup. A project that takes three days to set up is a project where anything can break the environment and nobody knows how to fix it.

It predicts environment drift. If setup is hard, people avoid rebuilding, and machines diverge.

Fixing it, in order

Automate the setup. A single script or command that installs and configures everything. It will not cover every case and it should cover the common one.

Move credentials to the front, and raise them in parallel rather than in sequence.

Prime the cache. A new machine should download build outputs rather than compute them.

Test the script in CI, on a clean image, on a schedule. This is what stops the documentation from rotting: the setup path is exercised automatically.

Provide a fallback — a container or a cloud environment — for anyone whose machine will not cooperate.

The maintenance problem

Setup instructions decay faster than any other documentation, because they are read once by each person and then never again.

A scheduled clean-machine run is the only reliable defence. If it fails, the setup is broken and you found out before a new joiner did.

Owning it matters. Without an owner it decays, and the decay is invisible until someone joins.

What to report

Time from clean machine to running application.

Time to first merged change.

Number of manual steps.

Number of times the new person had to ask. This is the most diagnostic of the four and the least often recorded.

Re-measure twice a year. It only ever gets worse on its own.

The clean-machine job

The check that stops setup documentation from rotting.

A scheduled CI job on a clean image that runs the documented setup path end to end.

Weekly, which is frequent enough to catch a break before someone joins.

Failing loudly, to whoever owns the setup.

Including the credential steps where they can be automated, and flagging where they cannot.

Without this the documentation decays silently, and the discovery mechanism is a new joiner losing a day.

Counting the questions

The most diagnostic number in an onboarding measurement and the least often recorded.

Every time the new person had to ask someone is a gap in the documentation or the tooling.

Log them, with what was asked.

The list is the work queue, ranked by how often each question recurs across joiners.

Most are one-line documentation fixes, and each removes an interruption from both people permanently.

Ask the second joiner to log them too, because the first list is always incomplete.