Short answer
Write it as a checklist of the first week's real tasks, then do the part the templates skip: give the newest person edit access to it on day one. Onboarding documentation is tested properly once per hire, by the person who has just hit every gap in it and usually cannot change a line.
Every guide to this question answers the same half of it. What sections to include, which template to copy, which knowledge base to buy, who to name as the maintainer. That advice is fine and most of it is correct. It also leaves the document in exactly the state that makes onboarding documentation famous, which is confidently wrong in three places that nobody has noticed since the last person joined.
The reason is not that the writing was lazy. It is that onboarding documentation is the only documentation whose entire readership turns over every time it is read. It gets one real test per hire, performed by the person best placed to see what is broken and worst placed to do anything about it. On day one they have the least access, the least context and the least standing to edit a line of it. So they do what everyone does: ask in chat, get unblocked in four minutes, and leave the document wrong for the next person.
What actually goes in onboarding documentation
Take the standard answer, because it is a good one. Microsoft's code-with-engineering-playbook ships an onboarding guide template with six sections: Overview and Goals, Contacts, Team Agreement and Code of Conduct, Dev Environment Setup, Project Building Blocks, Resources. That is close to the whole job, it is free, and if you have nothing today you should copy it this afternoon rather than read the rest of this page.
Two things are worth adding to it from practice:
- The things that are true but undocumented because they are embarrassing. The service that has to be restarted in a particular order, the staging credential that lives in one person's password manager, the test that fails on every fresh checkout and is safe to ignore. These are the lines a new hire actually gets stuck on and the lines a template will never prompt you to write.
- The decisions, not just the instructions. A setup step tells someone what to type. An architecture decision record tells them why the thing they are about to question is the way it is, which is the question they will have on day four rather than day one.
So the content question has a known answer. The failure is downstream of it.
Why it goes stale between the second hire and the third
Documentation rots in a specific way here, and it is worth being precise because the usual prescriptions aim at the wrong target.
The standard fix on every page ranking for this query is a named maintainer and a last-updated date. Both are reasonable and neither works for this document. A named maintainer is, by definition, somebody who already knows how to do everything in it, which means they are structurally incapable of noticing the gap. Expertise is what removes the ability to see the step you now do without thinking. A last-updated date tells a reader the page was touched, not that the line they are reading is still true, and it is itself the first thing to go stale.
The one person with the real information is the person reading it for the first time. They are holding a complete, time-stamped list of everything wrong with the document, and that list is destroyed at the end of their first week when they stop being new. Every hire regenerates it from scratch and every hire throws it away.
GitLab is the best-known team that solved this, and it solved it by changing who is allowed to edit rather than by changing what is written. Its handbook is explicit that the correction path is the only channel: "To propose a change to a process, make a merge request to change the handbook. Don't use another channel to propose a handbook change (email, Google Doc, etc.)" It is equally explicit about what the document is for: "the handbook is not what we hope to do, what we should formally do, or what we did months ago. It is what we do right now."
Note what is doing the work in that. Not a template. Not a review cadence. The fact that the person who just hit the gap can close it themselves, immediately, in the canonical copy.
Who should be able to edit it on day one
The honest answer is the newest person, and the reason most teams do not do it is that their tool makes the grant too coarse to be safe. Giving someone edit rights on the onboarding folder usually means giving them edit rights on a great deal else, so nobody does it, so the correction never lands.
That is a permissions problem wearing a documentation problem's clothes, and it is worth looking at what the common tools actually offer.
Notion gets closest of the mainstream options and deserves the credit. Its sharing documentation defines "Can edit" as the level that lets people modify page content while preventing them from sharing it, and "Can comment" for "people who should only have the ability to comment on a page". Inheritance works the way you would want: "When you create a subpage inside of a page, that subpage will take on the permissions of its parent page." If your team is on Notion and happy there, the move described in this post is available to you today, and you should go and make it.
Confluence is the instructive counter-example, because its own knowledge base admits the gap in one sentence: "Only view restrictions are inherited, Edit permissions are not inherited." So a space can be arranged such that a new hire sees the right subtree, and the edit rights have to be set page by page down the whole tree by hand. The thing you wanted to grant is the thing that does not cascade. (Our comparison with Confluence goes through the rest of that trade.)
Baalda, the app this site is for, is built around this being a first-class question rather than a setting. A share resolves to one of three levels, edit, view or none, computed on the server for every request rather than trusted from the client. Folder grants inherit to every descendant, and a share on an individual file can only raise someone's permission, never lower it. So "the newest person can edit the onboarding folder and view everything else" is one grant on one folder, and it applies to every note anyone adds under it afterwards without anyone revisiting the decision.
What stops the newest person breaking something
This is the objection, and it is a fair one. Some of what lives near onboarding documentation genuinely should not be editable by someone on their first morning: the security policy, the incident runbook, the thing with legal review on it.
Baalda answers it with a separate overlay rather than with a lower grant, which is the part that makes the whole arrangement work. A lock is a share row with permission = 'locked', set on a file or a folder, and it is resolved after the grant rather than instead of it. Three properties matter:
- It caps the result at
view. Someone who would otherwise have hadeditgetsview, and the app can tell the difference between "not shared with you" and "shared, and capped". - It applies to owners and admins too. The point of a lock is protecting content from accidental edits, so nobody is exempt. An owner who needs to change a locked file unlocks it first, deliberately, through the shares API.
- It never grants. A lock on something you could not see leaves you unable to see it:
nonestaysnone.
A lock cannot be set on a whole vault, only on folders and files, which is deliberate: a vault-wide lock would be a posture, not a protection, and the vault already has one of those.
Put the two together and the arrangement is two rows rather than a process. Grant edit on Onboarding/ to the person who joined on Monday. Lock Onboarding/Security-policy.md. Nobody reviews anything, nobody is asked to approve a typo fix, and the line about the staging credential gets corrected by the only person who knew it was wrong, in the copy everyone else reads. If you want the longer argument for why a permission decision has to be resolved by something in the path rather than by a convention, per-file permissions need a server that can say no is that post.
What happens when the new hire's assistant reads it
This is the half the vendor guides have not caught up with, and it changes the shape of the problem.
A new hire in 2026 does not read the onboarding doc top to bottom. They point an assistant at it and ask it questions, which is genuinely the fastest onboarding tool anyone has ever had and is also the fastest way to discover that the document is wrong. The assistant answers confidently from a stale line, the new person follows it, and the failure now arrives with more authority behind it than the document had on its own.
In Baalda the assistant connects to the same vault over an MCP endpoint, POST /api/mcp, with a bearer token minted per person and scoped to one vault. The useful property is that the token is not a second access system. Every one of the 22 tools resolves against the same permission function the app uses, per call. A note the person cannot see does not appear in list_notes at all, so the new hire's assistant reaches exactly the folders the new hire reaches and nothing else, which on day one is the entire point.
Because the grant was edit rather than view, the assistant can also close the loop. When the new person works out what the setup step should have said, edit_note writes it back into the same file: targeted replace, insert before or after an anchor, or delete, without resending the body. Each anchor has to match exactly once, and a missing or ambiguous anchor refuses the whole call with nothing written, so a confident model with a vague instruction fails loudly instead of rewriting a paragraph it half understood. Passing expectedRevision from read_note refuses the write outright if the note changed in between.
The files are plain .md on disk the whole time, so the person who maintained the document last week opens it in their editor and sees the corrected line, not a suggestion queue. If you are writing instructions aimed at the assistant rather than the human, how to write an AGENTS.md file covers the file every agent loads unconditionally, and what it costs to put the onboarding guide in it.
Where this does not help
Four things, plainly.
It does not write the document. Nothing here produces the six sections. The template at the top of this page does, the vendor guides on this query do, and that work is still yours. Access control makes a document correctable; it does not make it exist.
Most of onboarding is not documentation at all. It is hardware, accounts, SSO, VPN, payroll and the IT ticket that was supposed to be raised last Thursday. A large share of searches for this phrase are really about the HR paperwork pack, and a notes app is the wrong tool for every part of that.
A `view` default is sometimes correct. If you are in a regulated environment where the audit question is who could have changed a document rather than who did, open edit on arrival is not a trade you are allowed to make. Take the comment-and-review route instead and accept the latency.
For a team of three this is all overhead. Give everyone edit on everything, tell each other when something is wrong, and come back to this when there are enough of you that "tell each other" has stopped scaling. Most of the machinery on this page exists for the range from about ten people to about fifty, which is the same range in which a shared second brain starts earning its keep.
The short version
Write the six sections. Then do the part that decides whether they stay true: hand the newest person write access to them on their first morning, and lock the few files that genuinely must not move. The person who has just been confused by your documentation is the only person in the company who can see what is wrong with it, and they are holding that information for about five days.