Learn

Onboarding collaborators: a complete guide

Why onboarding documentation matters

Most people onboard collaborators the same way: show them around in a call, answer questions as they come up, and figure the rest will sort itself out. The result is a lot of questions that interrupt your work, inconsistencies that creep in because nobody's sure of the conventions, and a new collaborator who feels uncertain about where things belong and why.

A small amount of documentation fixes most of this. Not a manual, just enough that someone new can read through it, understand what the workspace is for, know where things go, and know who to ask if something's unclear. Once that's in place, onboarding becomes largely self-service, which is better for both you and the person joining.

This guide assumes you already have a structured workspace. If you haven't set that up yet, the collaborative workspace guide covers that first.

Step 1: document the purpose and structure

The first thing a new collaborator needs to understand is what the workspace is for and what the main areas are. This sounds obvious but almost nobody writes it down, which means every new person has to infer it from the structure or ask someone.

Create a dedicated section for onboarding and support documentation, somewhere visible and clearly labelled. Keep everything in one place rather than scattered across the workspace. Asking someone to hunt for documentation while they're still getting their bearings is the fastest way to create a poor first impression.

Inside this section, start with an "About this workspace" note. A short paragraph explaining what the workspace is for, what kinds of things belong in it, and what doesn't. It should be readable in under two minutes and give someone a clear picture of the purpose before they see anything else.

Below that, describe each main area: what it contains, what it's used for, and who is responsible for it. A few sentences per area is enough. The goal is a collaborator being able to read this and immediately understand the shape of the workspace before they touch anything.

Step 2: explain the key processes

Structure describes what exists. Process describes what happens. A new collaborator who understands the structure but not the processes will still be confused about what to do with things once they encounter them.

You don't need to document every edge case. Focus on the main flows: how does a new request get into the system? How does work move from one stage to the next? Who is responsible for handoffs between areas? What does "done" look like for the main types of work?

Write each process as a clear sequence of steps. If you use a Kanban-style workflow, describe what moves items between columns and who moves them. If you use an inbox-to-done flow, describe how items progress and who is responsible at each stage.

The most important thing to make explicit is who is responsible for handoffs. When work moves from one person or area to another, ambiguity about who does the moving is how things fall through the cracks. State it clearly: "When design is complete, the designer moves the item to Review. The client is responsible for moving it to Revisions or Done."

For teams using push vs pull workflows, documenting which system you use prevents the default behaviour (everyone assumes someone else will move it) from taking over.

Step 3: create a place for questions and feedback

Even with good documentation, new collaborators will have questions, notice gaps, and occasionally want to suggest changes to how things work. Give them a structured place to do this rather than leaving them to figure out the right channel.

A Discussions section within the support documentation works well. A few sub-sections helps keep it organised:

Questions. For anything unclear about how the workspace works or what to do in a particular situation.

Suggestions. For ideas about how to improve the structure or processes. This matters because the people using the workspace daily will see things you won't, and capturing their suggestions means improvements actually get implemented rather than mentioned once and forgotten.

Issues. For flagging anything broken, inconsistent, or unclear in the existing documentation.

This section also serves a useful secondary purpose: it's a record of what was confusing during onboarding, which tells you what to improve in the documentation for the next person.

Step 4: polish and sequence

Before sharing the documentation with a new collaborator, make sure it's readable in a logical order. Number the sections or label them clearly so it's obvious what to read first. "Start here → About this workspace → How each area works → Key processes → Where to ask questions" is a simple progression that works for most setups.

Read through it as if you were new. Does the purpose section actually explain the workspace clearly, or does it assume knowledge you already have? Are the process descriptions specific enough to follow, or are they vague enough to require interpretation? Would you be able to sit down and start contributing after reading this, or would you still need to ask several questions?

If you're working in Fabric, you can publish the onboarding documentation as a URL the new collaborator can access before they're added to the workspace. This means they can read through the structure and processes before they see anything else, which makes the actual access feel less overwhelming.

What to cover in a brief onboarding call

Even with good asynchronous documentation, a short call or walkthrough adds significant value. It doesn't need to be long. Fifteen minutes is usually enough to:

Walk through the documentation so they know where to find it. Most people won't read documentation they weren't explicitly pointed to.

Show one or two real examples of how a typical item moves through the workflow. Seeing it happen once is worth more than reading a description three times.

Confirm they know where to ask questions and that asking questions is expected and welcome. New collaborators often stay quiet rather than ask, which means problems take longer to surface.

Leave time for their questions. The questions that come up immediately after seeing the workspace for the first time are often the most useful signal about what the documentation is missing.

Sharing and access

When you're ready to add someone to the workspace, think carefully about what they actually need access to. In Fabric, you can share a specific folder or space at the permission level that makes sense for their role: viewer for materials they need to see but not edit, editor for areas they'll actively contribute to.

Don't give everyone access to everything by default. It creates cognitive overhead (more to navigate than they need), and it means sensitive materials are visible to people who don't need to see them. Sharing precisely what someone needs also signals that access has been thought about, which tends to be reassuring rather than restrictive.

For external collaborators (clients, contractors, occasional contributors) who don't need full workspace access, published pages let you share specific materials at a URL without requiring them to create an account or log in. This is useful for sharing deliverables, resource libraries, or reference materials with people who are participating in the work but not part of the team.

As the team grows

The onboarding documentation that works for three people may need updating for ten. Watch for the questions that keep coming up. If multiple people ask the same thing, that's a gap in the documentation.

Review the documentation every few months with the team. Is everything still accurate? Are there processes that have changed but weren't updated in the docs? Is the support section being used for questions, and have those questions been resolved and fed back into the documentation?

The best collaborative workspaces have documentation that improves incrementally over time based on real use rather than staying fixed as a snapshot of what seemed right on the day it was written.

Templates for recurring work types (new client onboarding, weekly review, project kickoff) reduce the amount of process knowledge someone needs to hold in their head, because the structure of the work is built into the template rather than relying on people to remember conventions.

Frequently asked questions

How much documentation is enough?

Enough that someone can start contributing without asking basic questions, and not so much that it takes an hour to read. Most workspaces need: a purpose statement (one paragraph), area descriptions (a few sentences each), two or three key process flows, and a place for questions. If you're writing more than a few pages, you're probably documenting edge cases that can wait until someone actually asks.

What if the workspace changes frequently?

Keep documentation in a single, findable place and update it when things change. If your processes are evolving rapidly, note that in the documentation so collaborators aren't surprised when what they read doesn't match what they see. A note like "this workspace is actively being refined; the Discussions section is the best place to flag anything that seems inconsistent" sets the right expectations.Should I onboard people asynchronously or in a call?

Both, for most cases. Asynchronous documentation means they're not dependent on your availability and have something to reference later. A brief call means they've actually absorbed the key points and have had a chance to ask questions. The documentation is primary; the call reinforces it.

What if collaborators don't read the documentation?

Point them to it explicitly when you share access, and reference it when questions come up ("that's covered in the How it works section"). Most people don't read documentation they weren't explicitly told exists. Making it the first thing they see, labelled clearly, and brief enough to finish in ten minutes improves the reading rate considerably.

How do I handle collaborators who ignore the agreed processes?

Usually it means the process wasn't clear enough, the documentation wasn't read, or the process doesn't actually fit how the work happens in practice. Before assuming the person is at fault, check whether the documentation describes the process clearly and whether the process itself is working. The Discussions section is useful here: if a process is being consistently ignored, that's worth surfacing as a topic for review rather than just chasing compliance with something that might need changing.