Fixing onboarding docs based on gaps you've actually watched new joiners hit, including the 'why' behind non-obvious setup steps, and testing a doc by having someone unfamiliar follow it literally.
Published September 23, 2026
The most valuable onboarding documentation improvements don't come from imagining what a new person might need — they come from directly OBSERVING where a real new joiner actually got stuck (a step that assumed context they didn't have, a command that silently required a prerequisite the doc never mentioned). This is a genuinely different, more reliable source of improvement than an experienced engineer trying to guess gaps from memory — someone who's been on the team for years has lost the ability to see which steps are actually non-obvious, because everything has become invisible, assumed background knowledge to them.
Thin (command only):
"Run `export AWS_PROFILE=dev` before starting the app."
Better (command + why):
"Run `export AWS_PROFILE=dev` before starting the app — the app reads AWS
credentials from this profile to reach the dev S3 bucket (see S3); without it,
you'll get a confusing 'Access Denied' error that looks like a permissions bug
rather than a missing environment variable."
A command-only instruction gets someone unstuck for THAT specific step, but leaves them without any transferable understanding — the next time something ADJACENT goes wrong (a similar but not identical AWS credentials issue), they're stuck again with no mental model to draw on. Including the WHY (what this step actually does, and what breaks if it's skipped or misconfigured) is a small amount of extra writing effort that pays off every time a related-but-not-identical issue comes up later — directly the same principle as Mentor a Junior or New Joiner's "understanding actually landed" concern, applied to written documentation instead of live pairing.
This is the single most reliable way to find a documentation gap: hand the doc to someone who's NEVER done this setup before, ask them to follow it EXACTLY as written (not filling in gaps from their own general knowledge, which defeats the test), and watch — silently, resisting the urge to jump in and clarify verbally the moment they hesitate — where they actually get stuck. Every point of hesitation or wrong turn is a genuine gap in the doc, not a gap in the reader's competence; a doc author testing their own doc by re-reading it themselves almost never catches these gaps, because they already know what the doc MEANT to say, which is precisely the knowledge a genuinely new reader doesn't have.
Q: How often should onboarding docs actually be re-tested this way? A: At minimum, whenever the underlying setup process changes meaningfully (a new required tool, a changed step) — and ideally with every genuinely new team member as a natural, low-cost opportunity, since a new joiner following the doc for real IS the test, if someone deliberately watches and captures where they got stuck rather than just answering their questions in the moment and moving on without updating anything.
Q: Isn't watching someone struggle through onboarding, rather than just helping immediately, a bit like withholding help unfairly? A: This is a genuinely different situation from Unblock, Don't Solve's mentoring context — the goal here isn't the new joiner's LEARNING (onboarding setup isn't usually meant to be a discovery exercise), it's DIAGNOSING THE DOCUMENT; a reasonable approach is letting them try for a bounded, short time to observe the genuine friction point, then helping directly and immediately once the gap is identified, rather than extending discomfort for no pedagogical benefit.
Q: Does including the 'why' risk making onboarding docs too long to actually be read? A: It's a real tension worth managing deliberately — a good pattern is keeping the 'why' brief and optional (a short parenthetical or a linked reference, as shown above) rather than a lengthy digression, so someone in a hurry can skip straight to the command while someone who wants the context can still get it without derailing the doc's primary, scannable structure.
Q: How does onboarding documentation relate to Architecture Diagrams as a living artifact? A: The same staleness risk applies, and the same fix — onboarding docs go stale exactly as fast as architecture diagrams do when the underlying process changes without the doc being updated; treating doc updates as a normal, expected part of any PR that changes setup/tooling (not a separate, easily-forgotten cleanup task) is what keeps either artifact genuinely trustworthy over time.