# Module help and Show me

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

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:

| Page | What goes in it |
|---|---|
| **Overview** | What the module is for and where everything is |
| **Reference** | Fields, statuses, rules and calculations |
| **Who can do what** | Permissions in plain words |
| **Questions** | The FAQ |
| **What's new** | Changes 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 on | Example |
|---|---|
| Every input | `data-dv-field="job.customer"` |
| Every button | `data-dv-action="job.save"` |
| Every button that saves, submits, sends, approves or deletes | `data-dv-confirm="submit"` |
| Fields it must never touch | `data-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

> *"Write runbooks for adding a customer and sending a quote, with Show me steps, and make sure every button on those screens is named and the Send button waits for me."*

```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](article:cfb41dcb-edee-4f32-979c-d0f041eff1f8).
- **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.


Source: https://datavisions.ai/docs/creators/platform-services/module-help-and-show-me
