Onboarding Documentation That Survives Contact With a New Starter

TL;DR

• Onboarding documentation usually fails on findability and trust, not on writing quality. Most teams rewrite when they should retitle.
• Name pages after the question somebody asks, not the policy they belong to. This single change outperforms restructuring.
• State the audience in the first line. A page written for the average employee is quietly wrong for everybody who is not average.
• A visible review date does more for trust than any amount of polish, because a new starter cannot otherwise tell a live page from an abandoned one.
• One authoritative page per topic. Duplicates do more damage than gaps, because a gap sends people to a human and a duplicate sends them to the wrong answer.
• Write for retrieval as well as reading. A page that answers one question well is more useful than a page that covers a subject thoroughly.

Somebody writes a thirty page onboarding handbook. It is accurate, comprehensive and genuinely well written. Nine months later the same questions are arriving in the same channel, and the natural conclusion is that nobody reads anything.

That conclusion is wrong often enough to be worth challenging. In most cases people did try, could not find the part that applied to them, could not tell whether what they found was current, and asked a person because asking a person resolves all three problems at once.

The real issue is not that documentation goes unread. It is that reading is the wrong model. Nobody reads onboarding documentation. They interrogate it, at a specific moment, with a specific question, and the page either answers that question or it does not.

Recommended Tools

Best tools for HR Operations

B BambooHR HR management system R Rippling HR & IT automation W Workday Enterprise HRIS

View all recommended tools

When documentation is not the problem

If the information is genuinely absent, writing is the job and no structure fixes it. This sounds obvious and is worth checking before any reorganisation, because teams frequently restructure content that does not exist. Log the questions for two weeks and mark which had a written answer. If most did not, the problem is upstream of everything in this article.

If the organisation has not decided, documentation cannot resolve it. A surprising share of unanswerable questions are not gaps in the writing. They are decisions nobody has made, resolved case by case for years, invisible because the inconsistency was distributed. Writing them down requires somebody to choose, and that is a different piece of work with different people in the room.

If nobody owns the content, improving it is temporary. A page that is excellent today and unowned will be wrong within a year, and the effort spent is effort you will spend again. Ownership is cheaper than quality and it compounds.

And the case that argues the other way. For a team of fifteen with stable processes, a single well organised document and a named person genuinely is enough, and building anything more elaborate is work that will not pay back. Scale the apparatus to the problem rather than to the aspiration.

Why pages go unfound

The mechanism is vocabulary, and it is almost always underestimated.

A page is named by somebody who knows the subject, so it gets the formal name: Travel and Subsistence Policy. The person looking for it does not know that term, because they have worked here for four days. They search for taxi, or for train, or for can I claim, and the document contains none of those words in a prominent position.

The search returns nothing useful. The person concludes, reasonably, that it is not written down. They ask a colleague. The content was complete, correct and well maintained, and it failed anyway.

This is why rewriting rarely helps and retitling often does. The content was not the problem. The index was.

The four properties a page needs

A title that is the question. Covered above and the single highest return change available. Keep the formal policy name inside the page for anybody who needs to cite it.

The audience in the first line. Policies that differ by contract type, location or grade are the most dangerous content you have, because they read perfectly and are wrong for a minority. A first line that says who this applies to converts a silent error into a visible one. A sentence beginning with the word all deserves a second look every time.

A visible review date and a named owner. The date is for readers, not editors, and it answers a question they cannot otherwise answer. The name converts a dead end into a route, and it is the element people most often leave off because a shared inbox feels tidier.

One answer, not a survey. A page that covers a subject thoroughly is harder to use than three pages that each answer one question. This runs against how most people were taught to write, and it is the adjustment that matters most if you also intend to put retrieval in front of the content later.

Writing for a reader who is interrogating, not reading

The practical consequence of the interrogation model is that structure beats prose.

Put the answer first. A page that opens with context, then background, then the rule, has buried the only part anybody wanted. If the expense limit is sixty, the first line says sixty and the reasoning follows for the small number of people who care.

Use the words people use. If everybody says laptop and the document says end user computing device, the document is wrong in the way that matters. Internal naming is worth preserving once, in a glossary, and worth avoiding everywhere else.

Keep each page to one decision. The test is whether you can state what question the page answers in a single sentence. If it takes two, it is two pages.

Make the exceptions visible rather than complete. Documentation that tries to enumerate every edge case becomes unreadable and still misses some. A page that states the rule clearly and then says that specific situations vary and names who to ask is both shorter and more honest.

And state what to do, not only what is true. A page explaining the policy on software requests without saying where to make one has described a situation rather than resolved it. Most unusable documentation is unusable for exactly this reason.

One more habit is worth adopting and it runs against instinct: say what the answer is not, where a reasonable person would assume otherwise. If the expense limit does not include travel, the page should say so explicitly rather than relying on the reader noticing that travel is covered elsewhere. Documentation written only in the positive leaves every unstated case to inference, and people infer generously in whichever direction suits the moment. A single sentence ruling out the common wrong assumption prevents more confusion than three paragraphs elaborating the correct one, and it is the kind of line that only gets written by somebody who has answered the question a few times and knows where people go wrong.

Duplicates are worse than gaps

Teams worry about missing documentation and under-worry about having four versions of the same thing.

A gap has a safe failure mode. The person cannot find an answer, asks somebody, and gets a correct one from a human who knows the current position. Slow, but right.

A duplicate fails unsafely. The person finds a page, has no way to know it was superseded eighteen months ago, and acts on it with full confidence. Nobody is alerted, because from the outside this looks exactly like the system working.

Duplicates accumulate for the same structural reason wikis decay: creating a page is always defensible and removing one is nobody's job. The repair is a rule rather than a cleanup, because a cleanup without a rule simply resets the clock.

Pick one authoritative page per topic. Archive the others rather than deleting them, so existing links fail visibly rather than silently returning nothing. Keep a short log of what was archived, because the standard objection is that somebody might need it and a log turns that into a lookup.

The glossary nobody writes

Of all the documentation a company could produce, the one with the highest ratio of value to effort is a list of what things are called internally, and almost nobody has one.

Every organisation accumulates names that mean nothing outside it. A system called after the project that built it in 2019. A process named for the person who designed it. An acronym that expanded to something that no longer exists. A team whose official name and spoken name have diverged. None of this is written down anywhere, because to the people who use it daily there is nothing to explain.

A new starter encounters this constantly and asks about almost none of it. Asking what a word means feels like a worse admission than asking how a process works, because process questions suggest you are engaging and vocabulary questions suggest you are lost. So people infer from context, get it approximately right, and carry a slightly wrong model for months.

The fix is a single page, alphabetical, with one line per term: what it is, and where to go for more. It takes an afternoon to write the first version and it immediately becomes one of the most used pages you have. It also pays off twice, because if you later put retrieval over your documentation, the glossary is what lets the tool connect the word somebody used to the document that holds the answer.

Two rules keep it useful. Include the obvious ones, because obvious is a judgement made by people who already know. And include retired terms with a note that they are retired, because the old name survives in documents and in conversation long after the thing has been renamed, and a starter hearing both has no way to know they refer to the same thing.

Build it from evidence rather than from memory. Ask the last three starters to list every term they had to work out, and you will get a better first draft than any insider could produce.

There is a second category worth capturing in the same place, which is the terms that mean something different here than they do elsewhere. Most companies have at least one word borrowed from the wider industry and used in a narrower or looser sense internally, and those are more dangerous than the invented names. An invented name announces itself as something to ask about. A familiar word used unusually does not, so a new starter uses it confidently in its ordinary sense and is misunderstood for weeks before anybody works out why. Listing those with a short note saying what they mean here, as distinct from what they mean generally, takes a few lines and resolves a genuinely confusing class of misunderstanding.

What a good page looks like structurally

Most advice about documentation is about writing. The more useful constraint is structure, because structure is what makes a page usable at the moment of interrogation, and it is also what a retrieval layer reads.

A page that works has roughly this shape. A title that is the question. A first line that says who it applies to. The answer, stated plainly, in the second or third line at the latest. Then the qualifications, the exceptions and the reasoning, in that order, for the smaller number of readers who need them. Then what to do, with the actual link or form. Then who to ask, by name. Then the review date.

That order is close to the inverse of how most policy documents are written, which typically open with scope and purpose, proceed through definitions, and reach the operative rule somewhere in the middle. That shape exists because policy documents are written to be approved rather than used, and the approval audience and the reading audience want opposite things.

The practical test is whether somebody can get the answer from the first screen on a phone without scrolling. If the rule is below the fold, the page will be read as not containing it, because people do not scroll a page they are not yet confident is the right page.

Two structural habits cause most of the damage. The first is the long preamble, which buries the answer. The second is the embedded exception, where the rule is stated and then quietly amended three paragraphs later for a category of person who will not have read that far. Exceptions belong immediately after the rule or on their own page, never at the end.

And keep one decision per page. The temptation to cover a subject completely produces pages that answer six questions adequately rather than one question well, and in practice people searching for any one of those six do not find it.

Who maintains it, and the model that survives

Documentation quality is an ownership question wearing a writing costume. The best written page in your company will be wrong within a year if nobody is responsible for it, and a mediocre page with an owner will be correct indefinitely.

The model that fails is central ownership. One person or team nominally owns all documentation, which means they own the parts they understand and nominally own the rest. The parts they do not understand go stale, because confirming a fact they cannot verify requires chasing somebody who has no obligation to respond.

The model that works is distributed ownership with a central mechanism. The person who owns the subject owns the page, because they are the only one who can tell whether it is still true. What is central is the process: the review dates, the reminders, and the rule about what happens when nobody claims a page.

That last rule is the load bearing one. A page with no owner should be archived rather than reassigned, and announcing that in advance produces real owners for the pages that matter within a fortnight. Reassigning orphaned pages in bulk to a team produces nominal owners who review nothing, which is the appearance of the fix without the fix.

The review itself should be as cheap as possible, because expensive reviews do not happen. Confirming that a page is still accurate should be one click, take under a minute for most pages, and not require opening an editing interface. If your review process is heavier than that, it will be skipped and the dates will become decoration.

Set the defaults at creation rather than retrofitting them. Every new page gets an owner and a review date before it is published, which costs seconds at the moment of writing and is nearly impossible to add later across hundreds of pages.

Telling people when something changes

A policy changes and the document is updated. That is the end of the process in most organisations, and it is where a specific failure begins.

Everybody who read the old version still believes it. Documentation has no mechanism for reaching people who already consulted it, so a change propagates only to whoever reads the page after the change. For a new starter this is fine, because they will read the current version. For everybody else the old answer persists, and it persists most strongly in the people who were most diligent about reading the policy in the first place.

This is why so many organisations have a gap between what the documentation says and what people do, with no one acting in bad faith. The documentation is correct, it was updated properly, and nobody was told.

The handling is modest. Anything with a date, a threshold or a monetary figure should generate a short note in whatever channel people actually read, saying what changed and from when. Not a link to the updated page, which nobody opens, but the substance in a sentence. Anything that only clarifies wording needs nothing.

It also helps to keep a visible change note on the page itself, stating what changed and when, for the last two or three revisions. A reader who half remembers a different number can then confirm they are not mistaken, which is a small thing that prevents a surprising number of confused conversations.

The deeper point is that documentation is a reference system, not a communication system, and treating it as both is how organisations end up believing they have told people things they have only written down.

Five checks on what you already have

Search your own site for your five most common topics and count results. More than about three per topic, with none marked current, is the condition that makes documentation unusable for anybody new.

Open the content as a day one account. Not as an administrator with a live session. Permission boundaries routinely exclude new starters from the pages written for them, and the worst version renders partially with no indication anything is missing.

Time somebody finding your most asked answer. Use a real new starter if you can. Over ninety seconds from the home page is a retrieval failure, and no amount of further writing addresses it.

Check what share of pages were touched in the last year. Under a third means search results are largely historical.

Read the first line of ten pages. Count how many say who the page applies to. In most organisations the answer is none, and that is where the quiet wrong answers come from.

The questions with no answer, and what to do with them

Every documentation project surfaces a category that nobody plans for: questions where the answer does not exist, not because somebody forgot to write it, but because the organisation has never decided.

Can people take leave during probation. Is the expense limit per item or per trip. Does a day of training count as a working day for the purposes of the policy. Whether a particular tool is approved. These present as documentation gaps and they are not. They have been resolved individually, by different people, inconsistently, for years, and the inconsistency has never been visible enough to force a decision.

Writing documentation is what makes them visible, because for the first time somebody is trying to produce a single answer and discovering there is not one. This is genuinely one of the most valuable things the exercise does, and it is also the point at which most documentation projects stall, because the writer does not have the authority to decide and the decision requires people who are busy.

Split the list in two. Questions where a decision is easy and nobody much minds get decided on the spot by whoever owns the area, written down, and closed. Questions that are genuinely contested go on a short list for a real decision with the right people, and in the meantime the page says plainly that this varies and names who to ask.

What must not happen is the writer inventing an answer because it is faster than convening a meeting. That is how a policy gets made by somebody with no authority to make it, published with the full appearance of institutional backing, and discovered a year later when somebody relies on it. The act of writing documentation carries a quiet power that is worth naming before anybody starts.

Keep the list of what you decided. It is usually the most substantive policy work a team has done in a year, and it happened as a side effect of a writing project, which makes it easy to lose entirely.

Documentation people can actually use

Onboarding is where accessibility failures cost the most, because the person affected has been employed for a few days and has the least standing to raise it. Most choose to struggle quietly, and you will not hear about it.

The checks are not specialist. Can the content be read with a screen reader, which rules out anything that exists only as a scanned image or a photograph of a document. Is the contrast sufficient to read on a laptop in a bright room. Do links say where they go rather than saying click here, which is both an accessibility issue and a usability one. Is anything conveyed by colour alone.

Two failures are specific to onboarding and both are common. The first is the policy uploaded as a scan rather than as text, which is unreadable to a screen reader, unsearchable to everybody, and invisible to any retrieval layer you might later add. The second is a welcome video with no transcript, placed on the page everybody is told to start with, which means the first content some starters meet is content they cannot consume.

A transcript solves the second one and has a useful side effect: it makes the content searchable, so everybody benefits, including people who simply want to check one fact without watching eleven minutes of video.

There is also a quieter requirement. Some starters will need an adjustment in order to complete onboarding at all, and the route to request one should be visible on the first page rather than filed under benefits several clicks away. Making somebody hunt for that is the same failure as making them hunt for the expenses policy, with considerably higher stakes.

Preparing documentation for retrieval

If you intend to put an answering layer over this content, the preparation is mostly the same work, with three additions.

Consolidate first. A retrieval tool answers from what it was given, so pointing it at four versions of a policy produces a confident answer from one of them with no signal that the others existed. Where a human searching would have seen ambiguity and hedged, the tool removes that safety signal entirely. Consolidation before connection, in that order.

Connect documents rather than folders. Handbooks tend to live alongside offer templates, salary bands and the occasional file saved in the wrong place, and connecting a drive shares all of it. Naming the documents is twenty minutes slower and makes the question of what you shared answerable rather than approximate.

Write the refusal list. Decide in advance which categories the tool should decline: contract specifics, anything statutory, anything varying by jurisdiction, anything depending on an individual's own data. This is the shortest document in the project and it prevents the most expensive failures.

Matram is our own product, stated plainly rather than buried. It reads the documents you point it at, answers from them in the channel people already use, and declines outside them. Pricing is flat at $29, $69 and $199 a month with unlimited seats and a 30 day trial needing no card. Its limits are relevant here: it has no free tier, it is not an HRIS so it holds no records and runs no approval chains, and its actions reach HubSpot, Zendesk and webhooks only, so it can open a ticket but will not write back to any system of record. WhatsApp is coming soon rather than available. It will not improve your documentation, and pointed at stale pages it will repeat them more efficiently than a search box would.

BambooHR publishes Core at $10.25 per employee per month, Pro at $17.50 and Elite at $25 above twenty five employees, with an assistant bundled into Pro that answers from policies held inside the platform. Rippling starts from $8 per employee per month plus a monthly base fee. Workday publishes no rate at all, its pricing URL returning a 404. Enboarder, Leena AI and Moveworks publish nothing, and the Moveworks pricing page carries a Forrester study rather than a rate card.

The decision table

Where the documentation should live

Teams spend a lot of energy on which platform holds the content and comparatively little on the two questions that actually determine whether it works: can the intended reader reach it, and is there one of it.

Reachability is the one that catches people. Onboarding content frequently sits inside a workspace, team or group that a starter is added to during onboarding, which means the instructions for completing onboarding are behind a boundary that onboarding is meant to remove. The symptom is not always obvious. Sometimes it is a request access screen, which at least announces itself. Sometimes the page renders with sections missing and no indication that anything is absent, and the reader takes an incomplete document to be a complete one.

Test it properly rather than assuming. Open every onboarding page using a freshly created account with only the group memberships a day one starter has, in a private window so no administrator session is reused. Most teams who do this find at least one page that fails.

The second question is whether the same content exists in more than one system, which happens whenever a team adopts a new tool without retiring the old one. Running a wiki and a drive and a portal is fine if one of them is the source and the others point at it. It is not fine if all three hold independent copies, because they will diverge within a quarter and nobody will be able to say which is authoritative.

So the useful rule is one source per fact, reachable by the people who need it, with everything else linking rather than copying. The platform matters far less than most comparisons suggest, and teams that migrate in search of better documentation usually reproduce the same problems in a new tool within a year, because the causes were titling, duplication, ownership and permissions rather than the software.

If you do migrate, do the consolidation first and move the survivors. Migrating everything and consolidating afterwards means doing the hard part twice.

The cost of getting this wrong

The visible cost is the time people spend asking questions that were already answered, and it is real but modest.

The expensive failure is the confident wrong answer from a page nobody knew was stale. The person who acts on it has no way to detect the error, no reason to doubt an official internal page, and no standing to challenge it if they did. The organisation finds out later, indirectly, usually when a second person repeats the first one's misunderstanding.

The second cost is the one that falls on the people least able to absorb it. Documentation that is hard to use pushes everybody toward asking a human, and asking a human has a social cost that is highest for the newest, the most junior and anybody who already feels they are imposing. Those are exactly the people your documentation was supposed to serve, and poor retrieval quietly reallocates the benefit to the confident.

The third is compounding. Every undocumented answer given verbally is an answer that has to be given again, and the informal version drifts with each retelling. Three years of that produces a company where the written policy and the practised one have separated, and nobody can say when.

So the question worth asking is not whether your documentation is good. It is whether a person in their first week, using the words they would naturally use, can reach the current answer to your ten most common questions without asking anybody.

Knowing whether it is working

Documentation is unusually hard to measure because its success looks like absence: the question that did not get asked leaves no trace anywhere.

Page views are the obvious measure and the least informative. A page with high traffic might be essential or might be badly titled enough that people open it, find it is not what they wanted, and leave. A page with low traffic might be obsolete or might be perfectly good and only relevant twice a year. Neither number tells you which.

The measure that works is comparative and costs nothing. Take the ten most asked questions from a period before you did any work. After the changes, count how many of those ten are still arriving. The ones that stopped were findability problems and are now solved. The ones that continue are telling you something more specific: either the answer is genuinely ambiguous, or the people asking are not reaching the documentation at all, and those two have different fixes.

A second measure worth taking occasionally is time to answer. Ask somebody who does not know the answer to find your most common one, starting from wherever a new starter would start, and watch. Ninety seconds is a reasonable threshold. What you learn from watching is usually not what you expected, because the point at which they get stuck is rarely the point you would have predicted.

The third signal is qualitative and the most useful of the three. Ask three recent starters a direct question: what did you have to ask somebody that you think should have been written down. Not whether the documentation was helpful, which produces polite answers, but that specific question, which produces a list. Those lists are the best input to a documentation backlog that exists, and they cost fifteen minutes each.

What none of these measure is whether the content is correct, which no usage signal will ever tell you. Correctness comes from ownership and review dates, and it is worth keeping the two concerns separate, because a page can be heavily used, easy to find, and wrong.

Doing the smallest useful version

If this reads as a large project, the useful version is deliberately small.

Take your ten most asked questions from the last two months. For each one, confirm a current page exists, retitle it as the question, put the audience in the first line, add a review date and a named owner. That is the entire first pass, it covers the large majority of your actual question volume, and it can be done in a day.

Then stop and measure. Watch whether those ten questions keep arriving. The ones that stop were findability problems and are now solved. The ones that continue are telling you something else is wrong, usually that the answer is ambiguous or that the person asking is not reaching the documentation at all, and both are useful to know before spending more.

Expand by evidence. Every page you work on after the first ten should be one somebody actually asked about, which you now have a list of. Teams that get the most from documentation work are not the ones that documented the most. They are the ones that made the twenty things people actually ask boringly easy to find.

Frequently asked questions