Self-serve content that answers before users ask: writing for tours and tooltips

Help centers are built for people who already know something is wrong. A user hits a wall, opens a new tab, types a question, scans results, and — if your documentation is good — finds an answer. Every step of that journey happens outside your product, after the frustration has already landed.

In-app guidance flips the sequence. A tooltip pinned to the field people hesitate on, a tour step that explains the screen someone just opened for the first time, a checklist item that links straight to the setting it talks about — these answer the question before the user has consciously formed it. The catch: content written for a help center almost never works inside the product. It's the wrong shape, the wrong length, and it's organized around your feature list instead of the user's moment.

This guide is about writing self-serve content that's designed to be surfaced, not searched — the articles, tooltip lines and tour copy that power guided onboarding. It's written for the people who own onboarding content: product marketers, support leads, founders doing both jobs at once.

Searched content and surfaced content are different species

A help-center article assumes a motivated reader. They came with a question, they'll tolerate three paragraphs of context, and they'll scroll. Inside the product, none of that is true. The user is mid-task. A tooltip gets maybe twelve words of attention. A tour step gets twenty-five before the eye drifts to the Next button. An embedded card in an empty state gets a headline and one sentence.

That constraint changes what "good writing" means. In a help center, completeness wins. In the product, timing wins: the right twelve words on the right screen beat a perfect 800-word article nobody opens. The 800-word article still matters — but as the second layer, one click behind the moment, not as the front door.

So the working model is a ladder: tooltip line → short in-context card → full article. Each rung answers the same question at a different depth, and each rung links down to the next. Write the ladder as one unit, not as three disconnected assets.

Start from moments, not from features

The classic documentation plan mirrors the product: one section per feature, one article per setting. The onboarding content plan should mirror the journey instead. Before writing anything, build an inventory of hesitation moments:

1. Pull up your funnel or step-completion analytics and list every screen where new users stall or drop.
2. For each stall point, write the question a user would ask out loud at that exact moment — in their words, not yours. Not "About the ingestion pipeline" but "Why is my data not showing up yet?"
3. Sort by how many new users hit each moment in their first week.

That sorted list is your content backlog. At a typical B2B SaaS, the top of the list is depressingly consistent: what happens after signup, how to connect data or import existing work, where the first result shows up, how to invite a teammate, and what the empty dashboard means. If you write nothing else, write those five ladders.

Write the question first, then answer it in the first sentence

Every piece in the ladder starts life as a question phrased the way a user would type it. Keep the question as the article title — literally. "Where do I see my first report?" outperforms "Reporting overview" both in your in-app search and in the search engine snippet, because it matches the intent word for word.

Then answer in the first sentence. Not after a paragraph of positioning, not after a screenshot — the first sentence resolves the question, and everything after it is supporting detail:

Where do I see my first report? Your first report appears under Reports → Weekly as soon as your data source finishes its first sync — usually within 15 minutes of connecting.

A user who reads only that line got what they came for. That's the point. Answer-first writing feels wasteful to authors ("they won't read the rest!") and is exactly right for readers.

One moment, one idea

The tooltip rung of the ladder has room for a single idea. If your draft tooltip contains the word "also," split it. The same discipline applies one level up: a tour step should orient ("this is where your flows live"), not enumerate ("here you can create, duplicate, archive, tag, and export flows"). Feature enumeration is what the interface itself is for.

A practical length budget that has held up across products:

• Tooltip / hotspot: one sentence, 8–14 words, verb first.
• Tour step: heading of 4–6 words plus one sentence of 15–25 words.
• Checklist item: an action phrase — "Connect your first data source" — plus a one-line payoff: "so your dashboard fills itself."
• Article behind the moment: 150–400 words. If it needs more, it's covering two moments.

Write for the state of the screen

The same screen needs different words on day one and day thirty. An empty projects list is a teaching moment ("Projects keep your flows organized — create one to start"), while a full one needs nothing at all. First-run tooltips should never fire twice; a returning user who sees the same "Welcome!" hint three times learns to dismiss everything you show, including the one hint that would have saved their week.

This is less a writing rule than a targeting rule, but it has a writing consequence: label every piece of content you produce with the state it assumes. "New workspace, no data connected" reads very differently from "data connected, no report opened." When content and state disagree — a tooltip explaining a button that isn't visible in the user's plan — trust in every later hint erodes.

Retire what stops working

In-app content rots faster than documentation because the product moves underneath it. Set up a monthly pass over three numbers per piece:

• Interaction rate — of the users who saw it, how many clicked, expanded, or followed the link?
• Step completion delta — do users who saw it complete the step it supports more often than those who didn't?
• Instant dismiss rate — closed within a second means the content is noise on that screen.

A tooltip with high dismissal and no completion delta isn't neutral; it's training users to ignore you. Cut it. A step that stays red even with guidance usually means the flow itself needs design work — content was the wrong tool, and that's worth knowing too.

A worked example

Take the most common stall in data products: the user connected a source, the dashboard is still empty, and the first sync takes ten minutes. The ladder for that single moment:

• Empty-state card (headline + line): "Your data is on its way — first sync takes about 10–15 minutes. You'll get a nudge when your dashboard is ready."
• Checklist item: "Connect a data source ✓ → Watch for your first report (auto)."
• Article, answer-first: "If your dashboard is empty right after connecting a source, wait 10–15 minutes for the first sync to finish. Here's how to check sync status, what 'stuck on step 2' means, and when to contact us…"

Nobody searches "first sync duration" during those ten minutes — they just quietly conclude the product is broken. The surfaced version prevents the conclusion; the searched version would have arrived too late.

The payoff compounds

Every question answered in-flow is a support conversation that never starts, but the bigger prize is momentum: users who never stall don't re-evaluate their decision to try you. Self-serve content written for moments is activation work wearing a writer's hat — and it's some of the highest-leverage writing a SaaS team can do.