Onboarding documentation: the path from a fresh machine to a merged change

Goal

A newcomer reaches a first merged change by following documents alone, and the documents improve with every newcomer instead of decaying between arrivals.

Prerequisites

A README that answers the basic questions; a pool of small, labelled first tasks; a named owner for the onboarding path. The cited Google chapter argues that most projects deserve a "Hello World" document that assumes nothing and gets the engineer to make something real happen, and that the best time to write such a tutorial is when you first join a team. Diátaxis (cited) classifies this document as a tutorial: learning-oriented, a practical activity towards an achievable goal.

Steps

1. Write the path as one numbered sequence with the end state stated at the top: "at the end you will have opened, reviewed and merged a change". Everything not on that path goes elsewhere and is linked.
2. Give every setup step as an exact command with its expected output, and a check the newcomer can run ("the test suite reports N passed"). Prerequisites (accounts, permissions, hardware) are listed before step one, not discovered halfway.
3. Provide a map page with links only: repositories, environments, who owns what, the glossary, the communication channels, the release calendar. No prose that will go stale.
4. Point to the first task pool and the label that marks tasks as suitable; the doc says how to claim one and what "done" means here.
5. Require the newcomer to keep a log of every stumble, question and workaround during the first days, and to turn the log into pull requests against the onboarding documents as their first contributions.
6. Put an owner and a last-verified date on the path; re-run it from a clean machine when a newcomer arrives or at a fixed interval, and delete steps that no longer apply. The cited chapter describes freshness dates and marking obsolete documents rather than leaving them.
7. Keep an agent variant of the same path: non-interactive commands, no steps that require a browser login where a token can be provided, and an explicit list of actions the agent must not take (deploying, deleting, contacting people).

Expected result

Time from arrival to first merged change is bounded by the path, not by the availability of a colleague; the onboarding documents are the most frequently corrected pages in the repository.

Limits and test basis

The path covers mechanics, not judgement; understanding the domain still comes from working with people and from the design documents. Environments that cannot be reproduced on a clean machine (licensed tools, restricted data) need a stated fallback. No onboarding-time measurement is claimed.