> 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/best-practices/guides-build-maintain-and-make-them-effective.md).
# Guides: build, maintain, and make them effective
How to build guides that help end users complete tasks, keep selectors stable, and catch problems before they reach production.
A guide that end users abandon halfway through can do more harm than having no guide. It takes their time, teaches an incomplete process, and weakens trust in the Assistant[^1]. Most abandoned guides fail for the same reasons: too many steps, unclear instructions, or selectors that break when the application updates.
## How it works
{% stepper %}
{% step %}
#### Start with a goal, not a recording
Before opening the [Editor](/assistance/a-tour-of-the-editor.md), answer three questions:
1. **What should end users be able to do after finishing this guide?** If you cannot state the outcome in one sentence, the guide is trying to do too much. Split it.
2. **Who is this guide for?** If the answer is "everyone," reconsider. A guide for new users and a guide for experienced users covering the same process will differ in step count and explanation depth. Use audiences[^2] to target each version.
3. **How will you know it worked?** Tie the guide to a measurable outcome: a completion rate target, a reduction in support tickets for that process, or an improvement in Task Success in HEART.
{% endstep %}
{% step %}
#### Keep guides short and focused
Shorter guides get finished more often. Aim for around 12 steps. If a guide exceeds 20 steps, it is almost certainly covering more than one process and should be split.
**The first and last slides matter most.** The first slide sets expectations: what the guide covers and how long it takes. The last slide confirms what the user achieved and links to the next step (a related guide, a help article, or a return to the workflow). Both reduce abandonment.
**One idea per step.** Each step should contain one instruction. If a step has two instructions ("click the button and then fill in the form"), split it into two steps. Steps with too much text get skimmed. Steps with one clear action get completed.
**Match each step to what the user needs to do.** Some steps ask the user to click an element, some ask them to enter a value, and some only explain something before the user acts. Choose the step based on the action, and keep explanation-only steps for the start, the end, and moments that need context.
**Make guides reachable through multiple channels.** A guide in the Assistant is only useful if end users find it. Link guides from announcements, tooltips, support emails, and internal documentation using link boxes or trigger commands. The more places a guide is reachable, the more likely it is to be started.
{% endstep %}
{% step %}
#### Make selectors stable
{% hint style="info" %}
**Who this is for.** This section is for whoever builds and maintains guides. Stable selectors depend on how the application is coded. If you do not have access to the application's code, share this section with its development team.
{% endhint %}
[Selectors](/assistance/in-app-guidance/creating-selectors.md) determine which element each step targets. Unstable selectors are the most common cause of guide failures. When the application updates and an element's ID or class name changes, the selector stops matching and the guide breaks.
**Avoid dynamic IDs.** Many applications generate element IDs that change on every page load or per session (IDs containing random strings, timestamps, or session tokens). A selector built on a dynamic ID works during recording and breaks in production.
**Use stable attributes.** Look for attributes that do not change: `data-testid`, `aria-label`, `name`, or custom data attributes the development team maintains. If the application does not have stable attributes, ask the development team to add them. This does more for long-term guide stability than any fix made in the Editor.
**Use content selectors for single-language applications only.** A content selector matches an element by its visible text. This works well in single-language applications. In multi-language applications, it breaks when the interface language changes. For multi-language setups, prefer attribute-based selectors.
**Handle elements that appear late.** Some elements appear only after the rest of the page has loaded, which is common in single-page applications. The guide step may look for the element before it exists. A skip condition checks whether an element is present on the page, not what state it is in. If the element is not present within the retry window, the step skips instead of failing.
{% endstep %}
{% step %}
#### Test before publishing
A guide that works during recording does not necessarily work in production. Test every guide under real conditions before publishing.
{% hint style="warning" %}
**Saving a published guide makes changes live immediately.** When you edit a guide that is already published and select **Save**, the updated version goes live straight away. End users see the new version on their next interaction.
To iterate safely, either duplicate the guide (the copy is unpublished), make changes on the copy, then publish the copy and unpublish the original, or make all changes on the existing guide and test thoroughly before saving. A duplicated guide starts its content analytics at zero interactions, so keep this in mind when deciding which approach to use.
{% endhint %}
**Test on every page where the guide is visible.** A guide assigned to a display rule[^3] covering multiple pages must work on all of them. Page layouts, element loading times, and dynamic content may differ between pages.
**Test with different audiences.** If the guide targets a specific [audience](/administration/audiences.md), log in as a user who matches that audience and confirm the guide appears. Then log in as a user who does not match and confirm the guide is hidden.
**Test across browsers.** Element rendering and selector behavior can differ between Chrome, Edge, and Firefox. If the organization supports multiple browsers, test the guide on each.
**Check the step count after testing.** If testing revealed that steps need to be added (for edge cases, error states, or additional explanation), recheck whether the total step count still makes sense. A guide that grew from 12 steps to 25 during testing should probably be split.
{% endstep %}
{% step %}
#### Fix common problems
When a guide breaks or underperforms, the cause is usually one of these:
* **Element not found.** The most common error. The application updated and the targeted element moved, was renamed, or was removed. Open the step in the Editor, check the selector, and re-record against the current page.
* **Element hidden by application permissions.** The selector is correct, but the field, function, or dataset only exists for users with a specific permission in the underlying application. To everyone else, the step fails as "element not found." Check what permission the guide assumes and compare it with the audience the guide targets. If the two do not match, narrow the audience to users who hold the permission, or split the guide into a version per permission level.
* **Guide started on the wrong page.** The guide is opened from the Assistant on a page where the first target element does not exist, and it fails immediately. Add navigation steps at the start that lead the user to the correct starting page, each with a skip condition so users who are already there jump straight to the process. This makes the guide start cleanly from anywhere it is visible, instead of depending on a display rule alone.
* **Element moves on scroll.** The selector finds the element, but it is off-screen or behind a sticky header. Reposition the step or use a different target element that remains visible.
* **Dropdown or modal steals focus.** The guide step targets an element inside a dropdown or modal that closes when the user moves to the stepbox. Record the step so the interaction keeps the dropdown open, or add an intermediate step that opens the dropdown first.
* **Low completion rate without errors.** No step errors, but users abandon partway through. Check the step-level drop-off view to see where users stop. If drop-off concentrates on one step, the instructions may be unclear or the step may be unnecessary. If drop-off is gradual, the guide is too long.
* **Guide appears on the wrong page.** The display rule is too broad. Narrow it to the specific URLs where the guide is relevant.
{% endstep %}
{% endstepper %}
## How to know it is working
Track three things for each high-priority guide:
1. **Completion rate.** A well-built guide on a relevant process should have a completion rate that is stable or improving. A declining rate means something changed: the guide, the audience, or the application.
2. **Step-level drop-off.** If most users abandon at the same step, that step has a problem: unclear instructions, a broken selector, or an element that loads too slowly. Fix the step, not the whole guide.
3. **Alert notifications.** A guide generating repeated step errors needs immediate attention. Fix it before end users lose trust in the Assistant.
{% hint style="warning" %}
**Caveat.** A guide with a high completion rate is not necessarily a good guide. If the guide teaches a process nobody struggles with, it takes attention without adding value. Tie guides to real support ticket data or training gaps, not to a completeness target.
{% endhint %}
## Relevant articles
{% content-ref url="/pages/1S0Ysrf45iMPMs4rp5yk" %}
[Creating guides](/assistance/in-app-guidance/creating-guides.md)
{% endcontent-ref %}
{% content-ref url="/pages/eQPgnZdiJgIJ0ByK3cM1" %}
[Creating selectors](/assistance/in-app-guidance/creating-selectors.md)
{% endcontent-ref %}
{% content-ref url="/pages/brm1JWKM3yHqhKU1n5G2" %}
[A tour of the Editor](/assistance/a-tour-of-the-editor.md)
{% endcontent-ref %}
{% content-ref url="/pages/JAVVeLucPxhcVUV81Jw5" %}
[Tooltips: choose, write, and place them well](/best-practices/tooltips-choose-write-and-place-them-well.md)
{% endcontent-ref %}
{% content-ref url="/pages/xrl3g8ZSEVCM0qRA7ZCH" %}
[Content planning: how to structure a content set that scales](/best-practices/content-planning-how-to-structure-a-content-set-that-scales.md)
{% endcontent-ref %}
## FAQ
What is the ideal number of steps per guide?
Aim for around 12 steps. If a guide exceeds 20 steps, it is likely covering more than one process and should be split into two or more shorter guides.
How do skip conditions work?
A skip condition skips a step automatically based on whether a specific element is present on the page. It checks presence, not state: it cannot tell whether a checkbox is checked or a field is filled. A common use is navigation: if the element that marks the correct starting page is already present, the navigation steps skip and the user goes straight to the process. Skip conditions also stop a step from failing when its element does not appear within the retry window.
Should guides be interactive or explanation-only?
Use interactive steps (click, input) when the user needs to learn by doing. Use explanation-only slides when the user needs context before acting. Most guides benefit from a mix: an opening slide that sets expectations, interactive steps through the process, and a closing slide that confirms what was achieved.
What happens when a guide breaks after an application update?
The guide step that targets the changed element will fail, and if alert notifications are enabled, the team will be notified. Open the affected step in the Editor, check the selector, and re-record it against the updated page. If the application updates frequently, invest in stable selectors (data attributes) to reduce the frequency of breaks.
How can end users find guides outside the Assistant?
Guides can be linked from announcements, tooltips, emails, and internal documentation using link boxes or trigger commands. A guide that is only reachable through the Assistant depends on end users knowing the Assistant exists and searching for the right topic. Linking from multiple channels increases the chance the guide is started.
[^1]: The Assistant is the end-user-facing panel where guides, search, announcements, and help resources are accessible inside the application.
[^2]: An audience is a reusable group of users defined by rules about their attributes, behavior, or tag interactions. Audiences control who sees which content and can also filter analytics.
[^3]: A display rule is a URL-based condition that controls which pages content appears on.
---
# 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/best-practices/guides-build-maintain-and-make-them-effective.md?ask=&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.