Build a guided onboarding tour for Sheets

When Northwind hands a shared spreadsheet to a new team member, the tabs and custom menus make sense to whoever built them and nobody else. The usual fix is a “read me” tab that everyone ignores, or a colleague walking each newcomer through it in person — neither scales.

This script gives the sheet its own guided tour. The first time someone opens it, a sequence of dialogs walks them through the key features, one step at a time. Once they have seen it, the tour stays out of the way — but a menu item lets anyone replay it whenever they like.

What you’ll need

• A bound script — open the spreadsheet, then Extensions → Apps Script — so the tour runs inside that sheet.
• The tour copy itself: a short list of steps, written in the steps array, one string per feature you want to explain.
• Nothing else. PropertiesService remembers who has seen the tour and needs no setup.

The script

// The tour content — one string per step. Edit these to match the
// sheet you are onboarding people into.
const TOUR_STEPS = [
  'Welcome. The Clients tab lists every active retainer.',
  'The Projects tab tracks work in flight.',
  'Run "Northwind → Sync" to refresh all data.',
];

// Key used to remember, per user, that the tour has been completed.
const SEEN_KEY = 'onboarded';

/**
 * Runs on open. Shows the tour to first-time users and always adds
 * the Northwind menu so the tour can be replayed.
 */
function onOpen() {
  // 1. Show the tour automatically only if this user has not seen it.
  const seen = PropertiesService.getUserProperties().getProperty(SEEN_KEY);
  if (!seen) showTour(0);

  // 2. Add a menu item so anyone can replay the tour on demand.
  SpreadsheetApp.getUi()
    .createMenu('Northwind')
    .addItem('Show tour', 'startTour')
    .addToUi();
}

/**
 * Menu handler — starts the tour from the first step.
 */
function startTour() {
  showTour(0);
}

/**
 * Shows one tour step, then recurses to the next. When the steps run
 * out, it records that this user has finished the tour.
 * @param {number} step - Zero-based index of the step to show.
 */
function showTour(step) {
  const ui = SpreadsheetApp.getUi();

  // 1. Past the last step — mark the tour done and stop.
  if (step >= TOUR_STEPS.length) {
    PropertiesService.getUserProperties().setProperty(SEEN_KEY, 'yes');
    return;
  }

  // 2. Show this step as a numbered dialog.
  ui.alert('Step ' + (step + 1), TOUR_STEPS[step], ui.ButtonSet.OK);

  // 3. Advance to the next step.
  showTour(step + 1);
}

How it works

1. onOpen runs automatically every time the spreadsheet is opened. It checks PropertiesService.getUserProperties for the onboarded flag, which is stored per user — so the tour follows the person, not the file.
2. If that user has no flag, this is their first visit, so onOpen calls showTour(0) to begin the tour at step one.
3. Either way, onOpen builds a Northwind menu with a Show tour item, so the tour is always available to replay.
4. startTour is the menu handler — it simply calls showTour(0) to run the tour again from the start, ignoring the seen flag.
5. showTour displays one step at a time. It shows the current step in a numbered ui.alert dialog, waits for the user to click OK, then calls itself with the next index.
6. When the index passes the last step, showTour writes the onboarded flag into user properties and returns, ending the recursion. That user will not see the tour automatically again.

Example run

A new colleague opens the shared sheet for the first time. Three dialogs appear in turn:

Step 1 — Welcome. The Clients tab lists every active retainer.

Step 2 — The Projects tab tracks work in flight.

Step 3 — Run “Northwind → Sync” to refresh all data.

After clicking through, the onboarded flag is set. The next time they open the sheet, no dialogs appear — but Northwind → Show tour is there if they want a refresher.

Run it

The tour wires itself up — there is no trigger to configure:

1. Paste the script into the sheet’s bound Apps Script project and save.
2. Reload the spreadsheet so onOpen runs.
3. Approve the authorisation prompt the first time.
4. The tour shows automatically for a first-time viewer; everyone else finds it under the Northwind menu.

Watch out for

• onOpen is a simple trigger and runs with limited permissions. ui.alert and PropertiesService are allowed; calls that need broader authorisation (such as UrlFetchApp) would fail from here.
• The seen flag is per user and per script. A user who opens a copy of the sheet, or whose script properties are cleared, sees the tour again.
• The tour blocks the sheet while it runs — each ui.alert waits for a click. Keep it to a handful of short steps; a long tour becomes an obstacle.
• showTour recurses once per step. That is fine for a few steps, but it is not built for dozens — for a long tour, switch to a loop or a single HtmlService dialog with Next buttons.
• If onOpen errors before the menu is added — for example a typo in the steps array — the Northwind menu will not appear at all. Test edits before sharing the sheet.