Module help and Show me

Ship your module's help and runbooks, and let the Shotgun Assistant walk people through them on screen.

Copy page for AIUpdated November 9, 2026

The best module in the world still gets "how do I…?" questions. Ship the answers inside your module: help pages for looking things up, and runbooks for doing things step by step. Every workspace reads the help for the version it runs, the assistant answers questions from it, and with the Shotgun Assistant on, it can walk people through a runbook right on their screen.

Help pages in your module

Your module's Help button opens its help in a side panel. You write it as short pages in plain text with simple formatting: headings, lists, tables, pictures and even little flow diagrams.

Recommended pages:

PageWhat goes in it
OverviewWhat the module is for and where everything is
ReferenceFields, statuses, rules and calculations
Who can do whatPermissions in plain words
QuestionsThe FAQ
What's newChanges by version

A page can be marked admins only, for setup notes. That hides the page; it isn't security.

Your help is also your agent's knowledge. Every agent can search, read and list the help of the modules a person can open, and is told to answer how-to questions from it, citing where it found the answer. So write one heading per task, named the way people ask (Quote a lead, not Estimates), and say where the button is.

Runbooks: steps the assistant can show

Anything a person does, in order, is a runbook. Anything they look up stays in help.

A runbook is one job ("Send a proposal", "Approve a time card"), 3 to 12 steps. Each step has:

  • Who does it, as a role title (Office, Crew lead, Customer), never a person's name.
  • Where, such as Sidebar › Field Services › Customers › Add customer, then numbered actions quoting each label exactly as the screen shows it.
  • What you'll see when it worked.
  • Optionally why it matters, or a stop point warning.

Runbooks show first in your Help, under Runbooks. A workspace with the Runbooks module also gets them there, with Start Run and a guided walkthrough, refreshed whenever your module updates.

Show me

A runbook step can carry the moves the Shotgun Assistant makes to show it on screen: go to a page, click, type, choose, then stop at the button. The assistant moves a cursor through the steps in the person's own tab while they watch. Anything that saves, submits, sends or deletes always waits for the person to press it or click Allow. Moving the mouse or pressing Esc stops it.

A Workspace Admin turns this on in System settings › Shotgun Assistant, and people need Let assistants work in their browser in their roles.

Naming buttons so the assistant can find them

The assistant clicks by name, not by guessing. On your screens:

Put this onExample
Every inputdata-dv-field="job.customer"
Every buttondata-dv-action="job.save"
Every button that saves, submits, sends, approves or deletesdata-dv-confirm="submit"
Fields it must never touchdata-dv-sensitive

Names follow thing.field and thing.verb, in lower case. Lists built with the platform's table and forms built with the form engine are named for you.

Ask the Module Builder

json
// For developers: one step in ui/runbooks/10-send-a-quote.json
{"title": "Send the quote", "role": "Sales",
 "body": "Where: Sidebar → Quotes → the quote → Send\n\n1. Click \"Send\".",
 "expected_result": "The quote shows Sent.",
 "shotgun": [{"go": "QUOTES/list"}, {"click": "quote.open"}, {"ready": "quote.send"}]}

Good to know

  • The module check looks for this. Named buttons, a runbook for each main task and help that explains the screens are part of the review rules. See Publish a module: the module check.
  • Quote only labels that exist in your screens today. Old help pages can drift; the screen can't.
  • Keep codes out of the words. No permission codes, setting keys or web addresses in help text.
  • Never end a Show me on a save click. End on the button and let the person press it.

Can't find what you need? Contact support.