In-App Guidance: Designing The Docs Onboarding Flow

Most documentation traffic arrives through search results and shared links, from readers with one question to answer. They rarely see the homepage, the navigation or last week's release. New guides go unread, and the most useful ones stay hidden behind whichever page brought the reader in. For a product team, the cost shows up as low feature adoption and support tickets for questions the documentation already answers.

A short onboarding flow on the homepage meets readers at that point of entry. It points to the newest guide and the most useful parts of the interface in four prompts. Visitors see it once and can leave at any step. Every word of it lives in a version-controlled configuration file.

The Flow

Step	Type	Points to	Why it's there
1	Release announcement	Centre of the screen	Introduces the newest guide before the reader scrolls past it
2	Tooltip	Search	Most readers arrive looking for one field or status, and search is the fastest route to it
3	Tooltip	Reading Records card	Readers who already use the API need this guide first, and its title alone doesn't tell them that
4	Tooltip	Theme toggle	Long reference sessions are easier in the theme a reader prefers, and the toggle is easy to miss

Design Rationale

Four Steps Maximum

Every extra step raises the chance that a visitor leaves before the end. The flow is capped at the release announcement plus the three interface elements that most change how visitors move through the documentation.

Single Exposure, Exit At Any Step

The flow appears only on a visitor's first homepage visit. Leaving at any step counts as completion, so it won't come back uninvited. A link beneath the homepage buttons lets visitors replay it whenever they want.

140-Character Limit Per Prompt

Readers take in a prompt at a glance, with their attention still on the page beneath it. Each prompt is capped at 140 characters as a content standard, so it can be read in full without scrolling.

Responsive Anchoring

Interface elements shift between screen sizes. On mobile, search is an icon, while desktop shows a full input field. Each step lists its target elements in order of preference and attaches to the first one visible. If none is found, the step opens in the centre of the screen, and a layout change can't break the flow.

No Tracking Inside The Flow

The flow stores one flag in the visitor's browser to remember that it has been seen. It sends no usage data of its own.

Guide Definition

Copy, targeting rules and step order all live in one configuration file, kept apart from the code that renders the flow. Revising a prompt or reordering steps needs an edit to that file alone. Commercial in-app guidance platforms work the same way and store each guide as structured data instead of code.

{
  "id": "docs-onboarding",
  "version": 1,
  "name": "Docs onboarding tour",
  "targeting": {
    "pages": ["/"],
    "audience": "All visitors",
    "trigger": "First visit to the homepage",
    "delayMs": 800
  },
  "frequency": {
    "showOnce": true,
    "storageKey": "nvd-docs-tour-v1",
    "replayElement": "#tour-replay"
  },
  "steps": [
    {
      "type": "announcement",
      "title": "New: AI Draft Audit",
      "body": "Fifteen errors in one Gemini-generated NVD guide, and the review method that catches them before readers do.",
      "nextLabel": "Show me around"
    },
    {
      "type": "tooltip",
      "anchor": [".md-search__inner", "label.md-header__button[for='__search']"],
      "side": "bottom",
      "title": "Search Every Guide",
      "body": "Find any field, parameter or status across all guides. Try searching for vulnStatus or Deferred."
    },
    {
      "type": "tooltip",
      "anchor": [".grid.cards > ul > li:nth-child(2)"],
      "side": "top",
      "title": "Already Using The API?",
      "body": "Start here. This guide shows how to handle CVE records that arrive without an NVD severity score."
    },
    {
      "type": "tooltip",
      "anchor": ["form[data-md-component='palette'] label:not([hidden])", "form[data-md-component='palette']"],
      "side": "bottom",
      "title": "Light Or Dark",
      "body": "Switch themes here. Your choice is remembered on this device.",
      "nextLabel": "Done"
    }
  ]
}

Field	What it controls
targeting.pages	Which pages the flow can appear on
targeting.delayMs	How long the page settles before the flow opens, so it never interrupts a reader mid-scroll
frequency.showOnce	Whether the flow appears only on a visitor's first visit
frequency.storageKey	The flag that records the flow as seen. Raising the version in its name shows a revised flow to every visitor again
frequency.replayElement	The link that relaunches the flow on demand
steps[].anchor	The elements a step can attach to, tried in order
steps[].side	Where the prompt sits relative to its element

Success Metrics

The flow sends no events of its own. Connected to a product analytics platform such as Pendo, Appcues or Userpilot, it would be measured on completion, drop-off, click-through and replays.

Metric	What it indicates
Completion rate	Share of visitors who reach the final step
Step-level drop-off	The prompt where most visitors exit, identifying copy to revise first
Announcement click-through	Visitors who proceed from the release announcement to the AI Draft Audit
Relaunch rate	How often visitors replay the flow, a sign it works as a reference

Built With

The flow runs on Driver.js 1.3.6, an open-source library under the MIT license. It deploys through the same GitHub Actions workflow as the rest of the documentation.