See it as a diagram
Everything below, as a diagram you can edit. Describe yours and see it in seconds.
No account needed · Editable canvas, not a picture
Newcomers cannot detect a stale document
Staleness is normally caught by readers who know better. That correction loop is the only thing keeping most internal documentation survivable, and it does not exist for the one audience the onboarding doc is written for. The person reading it has no way to tell a sentence written last month from one written three years ago, and both read with equal confidence.
The cost lands in the least visible place. A new engineer who takes a wrong turn does not report a documentation bug, they quietly lose two days and conclude they are slow. By the time they know enough to spot the error, they have also learned to stop reading the doc, which is how the correction loop fails to start.
It is worth asking your team a blunt question: when did the onboarding page last get a real edit, as opposed to a name being added to a list. On most teams the answer is the last time someone was actively embarrassed by it.
What a week-one architecture page has to answer
Five questions, in this order. What runs. What stores state. What talks to what. What builds and ships it. And which directory holds which part of that, which is the question a newcomer asks most often and finds documented least often.
Those five map almost exactly onto the sections of a repository-grounded architecture doc: a component inventory with one line of role each, the infrastructure the components sit on, how the system builds and deploys, and short notes per notable directory. The directory notes section is the one nobody writes by hand and the one that turns a first pull request from an afternoon of grep into twenty minutes.
That last section is not guesswork either. Alongside the selected files, the generator receives a compact map of the repository: every directory down to three levels with the number of files it holds, so a src/services/ carrying forty files is visible even when none of those forty made the read. It is the cheapest orientation artifact in the whole set, and the one a newcomer would otherwise assemble by hand with find and a lot of scrolling.
The picture matters more here than anywhere else in the documentation set, because a newcomer has no mental model to attach prose to. A diagram with real provider icons, named zones, and labelled edges gives them somewhere to hang everything they learn in week two.
Generate the map, hand-write the culture
Split the page in two and treat the halves differently. The generated half is system shape: components, infrastructure, deployment path, directory layout, and the diagram. It is derivable, it is boring to write, and it goes wrong silently, which makes it the ideal candidate for automation.
The hand-written half is what no repository contains. Who to ask about the payments path. Which parts of the codebase are known-bad and deliberately not being fixed yet. Which decisions the team is still arguing about. What review actually expects, as opposed to what the contributing guide says. This half ages far more slowly, and it is the half a good onboarding doc is actually valued for.
The failure mode of most onboarding pages is that the derivable half is written by hand, badly and once, and crowds out the half only a human could have written.
Keeping it true on the day it is read
A linked repository re-syncs about once a day, regenerating both the diagram and the doc from the tracked branch, and skipping the work entirely when the head commit has not moved. The relevant property is not the frequency, it is that nobody has to remember. A new hire starting in November reads a page describing November.
Embed the diagram in whatever the onboarding page actually lives in with one markdown line, which works in Notion, Confluence, a repository README, or a docs site. Viewers do not need a Datadef account to see it, so the page works on a laptop that was set up yesterday and has access to almost nothing.
If different teams onboard onto different parts of the system, point separate diagrams at the branches or repositories they own. One connection can back several diagrams, so a platform team and a product team can each have the view that matches their week one.
FAQ
Why do onboarding docs go stale faster than other documentation?
Which parts of an onboarding doc should be generated?
Which parts should stay hand-written?
Does the new hire need an account to see the diagram?
Can different teams have different onboarding diagrams?