> For the complete documentation index, see [llms.txt](https://docs.userlane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userlane.com/assistance/in-app-guidance/creating-guides.md).

# Creating guides

What a guide is, what guides are good for, what teams build them for, how to record one in the Editor, and how to publish and maintain it.

A guide is a sequence of steps that walks someone through a process inside the application they are already working in. Each step highlights one element on the screen, shows a short instruction, and waits for the person to act before moving on. You build a guide by recording the process once, in the application itself, using the Editor[^1].

A step points at one element, such as a button or a field, and shows its instruction in a small panel beside it, the stepbox[^2]. A dimmed backdrop covers the rest of the page so stray clicks do not interrupt the process.

Each step finds its element through a selector[^3] recorded together with the step, which is how one recording keeps working across sessions and users. The guide teaches the process by having the person do it.

## What guides are good for

A help article asks someone to leave the task, search, and translate what they read back into the screen in front of them. A guide runs on that screen. It also holds up better than one-time training, which fades within weeks and is rarely at hand on the day the work has to be done. Where a process has to happen in a set order, a guide holds that order, and can require a field to hold a specific value before it moves on.

That suits four patterns in particular: onboarding into a new system, processes that come around too rarely for anyone to remember the steps, work where a wrong entry is expensive to correct, and feature launches where people need the path on the screen the feature lives on.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2FWiIsf4QZum83ob4qOld9%2FGuide%20welcome.png?alt=media&#x26;token=2698ba97-da7d-4c06-86d8-796c769a270e" alt="A guide running inside an application, with the stepbox beside the highlighted element"><figcaption><p>A guide running inside the application.</p></figcaption></figure></div>

## Creating a guide

Recording is the main way to build a guide. The Editor records clicks in the live application and turns each one into a step.

{% stepper %}
{% step %}

#### Open the Editor and create a guide

In the Editor, click **Create** to start a new guide.
{% endstep %}

{% step %}

#### Record your steps

Click through your process. The Editor records a guide step for every action.
{% endstep %}

{% step %}

#### Generate text

Each step carries a short message that tells the person what to do. To generate instruction text automatically, open the **AI** tab in the step editing panel and click **Generate text**. In the window that opens, enter a short description of the guide and, optionally, upload a PDF as source material. Click **Generate** and the content agent writes the instruction text. The generated text takes the target element into account, and you can edit it afterward.

<div data-with-frame="true"><figure><img src="https://259567114-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF6bxg8i3T6U4vZ3k7PHi%2Fuploads%2Fcyy8uj8dBOR7VyOUr7DD%2Fguide%20generate%20text.png?alt=media&#x26;token=daea4eeb-6eed-4665-a21a-7c50f2f120cd" alt="The Generate text window in the AI tab of the step editing panel"><figcaption><p>Generating step text from the <strong>AI</strong> tab.</p></figcaption></figure></div>
{% endstep %}

{% step %}

#### Configure the steps

Each step has settings that control how it behaves. You can refine the selector, change the alignment of the stepbox, and set the advance condition, required value, and skip condition. A step can also hold one image, one video, an external link, or an information box.

<table><thead><tr><th width="117.74609375">Setting</th><th>What it controls</th></tr></thead><tbody><tr><td><strong>Advance condition</strong></td><td>The action that moves the guide forward: clicking the target element, pressing a key, or clicking the <strong>Next</strong> button.</td></tr><tr><td><strong>Required value</strong></td><td>For a step on a form field, the value the field has to hold before the guide advances.</td></tr><tr><td><strong>Skip condition</strong></td><td>The page state that makes the guide pass over the step, such as the next step's element already being present.</td></tr></tbody></table>

A step can also advance on its own after a short delay, which suits steps that only confirm something.
{% endstep %}

{% step %}

#### Preview the guide

Preview runs the guide against the current draft, including steps that have not been saved, and can start from any step. Run it before publishing to confirm the guide works as expected.
{% endstep %}
{% endstepper %}

## Managing and publishing

Publishing makes a guide available to end users. A published guide reaches the people who match its [audience](/administration/audiences.md) and appears on the pages its display rules allow. It is also gated one level up: a published guide inside a chapter that is not published stays invisible. Publish it in every language its audience reads, because a guide with no content in the language a browser asks for does not appear at all. See [Languages](/assistance/content-operations/languages.md).

Unpublishing hides a guide from end users. It stays in the Editor, keeps its steps, and keeps the analytics it has already collected, so you can take a guide down during an application change and bring it back afterward.

{% hint style="danger" %}
**Edits to a published guide are live.**
{% endhint %}

Duplicating creates a copy with the same steps, targeting, and translations. The copy starts with a fresh analytics baseline, so the original and the copy are tracked separately.

Guides need revisiting after they go live. Content analytics show where people stop partway. Drop-off concentrated on one step usually means that step is broken or unclear. Drop-off spread across many steps usually means the guide is too long.

{% hint style="success" %}
**When an element moves.** The step that pointed at it is flagged in the Editor. You can point the step at a new element, or edit its stored selector directly. [Manage selectors](/assistance/in-app-guidance/creating-selectors/manage-selectors.md) covers both.
{% endhint %}

## Troubleshooting

<table><thead><tr><th width="201.01953125">Symptom</th><th width="177.9375">Likely cause</th><th>What to check</th></tr></thead><tbody><tr><td>The guide does not appear for end users</td><td>Something above it is hiding it</td><td>The guide is published, the person matches its audience, the current page matches its display rules, and the chapter holding it is published</td></tr><tr><td>The guide is published but still missing in the application</td><td>Cached content</td><td>Reload the application fully to force a fresh fetch, and confirm the guide is published in the language the browser is asking for</td></tr><tr><td>The guide skips ahead to the wrong step</td><td>A skip condition is true when it should not be</td><td>Whether the next step's element is already present on the page, and whether the current step's element can be found at all</td></tr><tr><td>The guide stops after a page change</td><td>The step that caused the reload is not marked as such</td><td>The reload setting on the step that submits or navigates, and whether the new page is inside the guide's display rules</td></tr></tbody></table>

## Relevant articles

{% content-ref url="/pages/CTLIhTmnhzt4Gwl4dF9h" %}
[Manage selectors](/assistance/in-app-guidance/creating-selectors/manage-selectors.md)
{% endcontent-ref %}

{% content-ref url="/pages/VZqRoAJSjPm9ZGD2jNVG" %}
[Create and manage content](/assistance/content-operations/authoring/create-and-manage-content.md)
{% endcontent-ref %}

{% content-ref url="/pages/BJ6uX7MdEouMq5jZDQtF" %}
[Creating validators](/assistance/in-app-guidance/validators.md)
{% endcontent-ref %}

{% content-ref url="/pages/L1pTwQHW0TmAMoPDFhLR" %}
[Creating Contextual Actions](/assistance/in-app-guidance/creating-contextual-actions.md)
{% endcontent-ref %}

{% content-ref url="/pages/HGvA2yvKz1f1Ux8Nm4PS" %}
[Guides: build, maintain, and make them effective](/best-practices/guides-build-maintain-and-make-them-effective.md)
{% endcontent-ref %}

## FAQ

<details>

<summary>What is a guide in Userlane?</summary>

A guide is a sequence of steps that walks a user through a process inside an application. Each step highlights one element, shows an instruction, and waits for the user to act before the guide advances.

</details>

<details>

<summary>What is the difference between a step and a slide?</summary>

A step points at an element on the page and waits for the user to interact with it. A slide has no target element and shows its message in the middle of the screen, which suits introductions, closing messages, and explanations.

</details>

<details>

<summary>Is a published guide visible to everyone?</summary>

No. A published guide reaches only the people who match its audience, on the pages its display rules allow. A guide inside a chapter that is not published stays invisible regardless of its own status.

</details>

<details>

<summary>What happens if the page reloads while a guide is running?</summary>

A step that submits a form or navigates has to be marked as causing a reload. When it is, the guide waits for the new page and continues at the next step. When it is not, the guide stops at that point.

</details>

<details>

<summary>Does unpublishing a guide delete its analytics?</summary>

No. Unpublishing hides the guide from end users and keeps both the guide and its historical analytics. You can publish the guide again later.

</details>

[^1]: The Editor is the workspace where Userlane content is built, separate from the portal where content is targeted and analytics are viewed.

[^2]: The stepbox is the small panel that appears beside the highlighted element while a guide is running. It holds the step's instruction, any image or video attached to it, and the navigation buttons.

[^3]: A selector is the rule Userlane uses to find an element on the page. If the application changes, the selector may need refining so it still matches.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.userlane.com/assistance/in-app-guidance/creating-guides.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.