Workflow Recording Best Practices

Why This Guide Exists

A workflow recording is not just a capture artifact. It becomes draft logic, QA context, and eventually user-facing guidance, so the source recording needs to be clear, stable, and safe to adapt.

Primary goal

Create a recording that survives review, preview, and publish.

Audience

Internal authors, reviewers, and operators preparing customer-facing help.

Next

Pair this page with Workflow Authoring and SDK Reference.

Prepare the Real Path Before You Record

Record Like You Are Teaching the User

• Prefer one workflow per intent. If the path splits early for different personas or plans, create separate recordings.
• Use visible product language in narration so the generated copy matches what the customer sees on screen.
• Avoid describing hidden logic, backend jobs, or reviewer-only controls in spoken notes unless they are required for internal QA.
• When a step requires user input, capture the prompt and expected action clearly so the resulting draft pauses in the right place.

SDK Deep Dive: What the Recording Hands Off To

The SDK is the runtime layer that turns a reviewed workflow into an in-product experience. Recording quality matters because playback depends on stable identity, stable targets, and a mounted UI surface.

For the runtime itself, start with the provider pattern from Quickstart and the launch behavior from Workflow.

import {
  ModelNexProvider,
  ModelNexChatBubble,
} from '@modelnex/sdk'

function AppShell() {
  return (
    <ModelNexProvider
      websiteId="your-website-id"
      userProfile={{
        userId: currentUser.id,
        type: currentUser.role,
        isNewUser: currentUser.isNewUser,
        features: currentUser.enabledFeatures,
      }}
    >
      <Routes />
      <ModelNexChatBubble appName="My Product" />
    </ModelNexProvider>
  )
}

When the workflow should begin from a visible in-product action, use a manual launch rather than relying on users to discover it through freeform chat.

import { useModelNex } from '@modelnex/sdk'

export function SetupButton() {
  const { startWorkFlow } = useModelNex()

  return (
    <button onClick={() => void startWorkFlow('FLOW_ID')}>
      Start Workspace Setup
    </button>
  )
}

User-Facing Guide Without Revealing Internal IP

Customer-facing guides should describe what the user sees, what they need to provide, and what success looks like. They should not reveal internal selectors, dev tooling, preview modes, or internal naming conventions.

A simple Markdown article works well for help centers, in-app docs, and support handoffs. Teams can start from this template and swap in product-specific labels.

# [Workflow name]

## What this guide helps you do
Complete [outcome] in [product name] without leaving the product.

## Before you start
- Make sure you have access to **[screen or permission]**.
- Have **[credential, project name, approval, or setting]** ready.
- Plan for about **[x] minutes**.

## Steps
1. Open **[screen name]**.
2. Select **[button label]**.
3. Enter **[user-provided information]** when prompted.
4. Confirm the result on **[success screen or confirmation state]**.

## If something looks different
- If you do not see **[button label]**, check your role, plan, or prerequisite setup.
- If the workflow pauses, complete the requested action and then continue.
- If the screen has changed, return to the last confirmed step instead of restarting from scratch.

## What success looks like
You should see **[success state]** and be ready for **[next task]**.

Review Before You Publish

Continue with Workflow Preview and Publish. Keep SDK Reference open nearby for runtime details and Knowledge Base for indexed support content.