How to build a software onboarding guide new hires will actually read

About one in five new hires leaves within the first 45 days, and roughly a third are gone in 90. (Source.) The reasons cluster around mismatched expectations, lack of connection, and poor onboarding. The fix is rarely a longer wiki page or a 4-hour Loom from the manager who doesn't have 4 hours. It's a different shape of doc.

This is a practical guide to building a software onboarding guide that gets read. Not a generic HR onboarding plan — the specific case where a new hire needs to learn how to use the tools your team uses every day. Jira. Salesforce. The internal admin panel. The deploy pipeline. The bespoke ticket system the founder wrote in 2018 that nobody has the heart to replace.

What new hires actually need in week one

Watch a new hire open a fresh wiki. They scroll. They Ctrl-F for the thing they were just told to do. They find a page from 2022. They try to follow it. The screenshots are from a UI version that doesn't exist anymore. They Slack their manager. The cycle repeats.

Three things, in order of importance, are what they actually need:

An exact, current sequence for the five workflows they'll do every day. Not a theoretical tour of the platform. The five things they'll repeat: creating a ticket, running the deploy, processing an expense, escalating a customer issue, whatever “real work” looks like for the role.
The name and current location of the person who owns each system. A wiki that says “ask Marcus” when Marcus left two years ago is worse than no wiki.
The URL of every internal tool, with one screenshot of what it looks like when you log in. You think your tools are obvious. They're not. The new hire is fighting six SSO prompts and doesn't yet know what “the admin panel” means.

An onboarding guide that nails those three things in week one beats one with sixty pages of culture deck.

Why wiki pages decay faster than you think

The half-life of a typical wiki onboarding page is maybe six months. Three reasons.

The screenshots get stale. Your tooling gets a redesign. The button moved. The screenshot in the wiki shows the old layout. The new hire doesn't know which is correct. The screenshot is now a riddle, not a hint.

The author writes from expertise, not memory of ignorance. The person who wrote the page hasn't been a new hire on this team in years. They skip the steps that are obvious to them. Those are exactly the steps the new hire needs.

Updates are a project, not a habit. Updating the wiki page after a workflow change means opening the wiki, finding the page, taking new screenshots, cropping them, captioning them, replacing the old ones, and saving. Nobody ever does this. Slack messages get sent instead.

The shape that survives is the one where updating the doc is no harder than running the procedure. Re-record, re-publish, done.

The walkthrough-first onboarding plan

Here's a structure that works for software-heavy roles. Adjust the count to match your team.

Page 1: Map of the world (15 minutes to read)

A single page that lists every tool the new hire will touch, with:

Tool name (Jira, Salesforce, GitHub, the internal admin panel)
What it's for, in one sentence
The URL
One screenshot of the post-login view
Who owns it (current name, not historical)

No procedures yet. Just orientation. The new hire reads this on day one and now has a mental model of where things live.

Pages 2–6: the five workflows (one walkthrough each)

Each of the five workflows the role does every day gets its own walkthrough. A walkthrough, not a wiki page. The new hire follows it click-by-click on real systems on their laptop.

Examples for a customer success role:

How to log a customer call in the CRM
How to escalate a critical bug to engineering
How to schedule a renewal call
How to pull the monthly usage report
How to update a customer's contract

Each walkthrough is recorded by the person who actually does it, while doing it. Not written by someone theorising about the procedure.

Page 7: How to ask for help

Channel names. On-call schedule. The Slack channel that answers the “is this normal?” question. The two people who don't mind being interrupted in week one. This is short on purpose.

What “walkthrough” means here

A walkthrough is a numbered sequence of steps where each step has:

A real screenshot of the actual screen
The URL of the page
The element that was clicked, identified by its visible text or label (“the ‘Log Call’ button next to the customer name”)
A one-line description if the screenshot doesn't make the step self-evident

The difference between a wiki page with screenshots and a walkthrough is the structure. A wiki page is prose with images embedded. A walkthrough is steps. The new hire scrolls through and the cognitive load per step is small.

UIHike captures all four of those fields automatically when you record a workflow. The screenshot, the URL, the clicked element with its visible text and associated label, and an editable description. You hit record, you do the work, you get the walkthrough.

The two-week build plan

If you're starting from a blank wiki, here's a realistic schedule.

Week 1, day 1. Write the Map of the World page. This is the only one you write by hand. List the tools, write the one-sentence purposes, paste the URLs, take one screenshot of each post-login view, name the owners. Two hours, max.

Week 1, days 2–4. Pick one person on the team per role. Have them record the five workflows for their role, while doing real work, over the next three days. Don't schedule a documentation session. Schedule the work, and tell them to hit record. Each workflow takes 15–30 minutes to record and another 15 to clean up. Total per person: roughly five hours, spread across three days.

Week 1, day 5. Pull the walkthroughs into the onboarding folder. Add the “How to ask for help” page. Test the whole thing yourself on a clean account: can you log in to each tool, follow each walkthrough, and reach the done state? Where you hit friction, leave a comment on the step.

Week 2. Hand it to the next new hire. Watch where they get stuck. Update the steps where they got stuck. The doc gets better with every new hire who runs through it.

The pitch for capture-while-doing

Three things change when the doc is recorded instead of written.

You don't skip the boring middle. The clicks that are muscle memory to you, the ones the new hire will be most confused by, get captured because you're not the one deciding what to write down. The recorder takes everything.

The URLs are real, not approximate. Every step has the actual URL of the page you were on, copied from your address bar in the moment. The new hire can paste it into their browser and land in the same place.

Updates are cheap. When the workflow changes, you re-record. You don't re-edit a wiki page screenshot by screenshot. The cost of keeping the doc current goes from prohibitive to barely-noticeable.

Sharing and access

Onboarding docs need to live in the place new hires actually open. Here are the practical patterns:

Public published link (go.uihike.com/published/{UUID}) — no login wall, fastest to share, supports comments and reactions per step. Use this if the walkthrough doesn't contain anything sensitive.
Team share — visible only to your team, authenticated through Google or Microsoft Entra ID. Use this when the walkthrough shows internal tools, customer data, or anything you don't want indexed.
Token share — a URL like go.uihike.com/share/{token}, no login required, but the URL itself is the secret. Useful for one-off shares with someone outside your tenant.
Markdown export into Confluence or Notion — if your wiki is the system of record, paste the walkthrough in there. The inline images survive.

Common patterns that fail

Three traps to avoid.

The 4-hour onboarding video. The manager records a single long Loom that covers everything. Nobody watches it twice. The 23-minute mark, where the answer to the new hire's specific question lives, is unreachable. Break it into walkthroughs by workflow.

The aspirational SOP. The doc describes how the procedure should work, not how it actually works on day one. The new hire tries to follow it, hits the real-world weirdness, and loses faith in the doc. Record the real flow, including the workarounds.

The page nobody owns. A wiki page that says “last updated 2024” is a warning sign. The walkthrough version solves this implicitly: the “last published” timestamp is automatic, and the cost of updating is low enough that it actually happens.

Start with one walkthrough

You don't need a 14-page onboarding plan tomorrow. Pick the workflow that the next new hire will need to do on day one. Record it. Publish it. Hand the new hire the link.

Try UIHike on whichever workflow your last new hire Slacked you about most often. The walkthrough you record this week is the one that doesn't need to be written when the next hire starts.

— The UIHike team