Authoring + editing tutorials
Open /admin/help-tutorials. The list shows every tutorial in the tenant with read counts and step counts. Click a row to edit, or + New to add a tutorial for an admin page that doesn't have one yet.
Anatomy of a tutorial
| Field | What it carries |
|---|---|
| page_key | The admin route's logical key — e.g. orders, vendors, settings/payment. The frontend passes this when requesting the tutorial. Must match the key the page declares. |
| language | A language code such as en or es. The resolver picks the user's locale, falls back to en. |
| title | One-line heading shown at the top of the help panel. |
| description | Short paragraph (1-3 sentences) under the title. Sets the goal of the tutorial. |
| steps | JSON array of { step, title, content, image_url? }. Steps are numbered automatically by the renderer; the step integer is just for stable ordering. content is plain text or markdown. image_url is optional — point at any served image. |
| settings_help | JSON array of { field, label, description, impact }. Drives the per-field hints next to form inputs on the same page. field is the form input's name. impact is a one-liner about consequences ("Disables checkout when off"). |
| video_url | Optional. YouTube / Vimeo / direct mp4 — the panel embeds it above the steps. |
| is_active | Off-switch without deleting the row. Inactive tutorials are skipped by the resolver. |
Common page_keys
The seeder ships keys for: dashboard, orders, orders/[id], products, products/new, categories, vendors, customers, usergroups, privileges, settings, settings/payment, settings/shipping, settings/tax, modules, themes, banners, promotions, coupons, reports, plus a long tail. When wiring a new admin page, pick a key that mirrors the route.
Best practices
- Steps under 7. A tutorial that needs more is two tutorials.
- Lead with the goal. The description should answer "why am I on this page?" in one sentence.
- Use settings_help for the 3 fields that matter. Don't annotate every input — that's noise.
- Re-seed after major UI changes. When the admin renames or restructures a page, update the corresponding tutorial. Stale tutorials are worse than no tutorials.
Programmatic seed (advanced)
The default tutorial set lives in defaultTutorialsEN() in backend/internal/core/admin/help_tutorials.go. To ship platform-wide updates, edit those lists and POST /admin/help-tutorials/seed per tenant — the upsert is idempotent, but only fills GAPS (it won't overwrite tenant edits to existing rows). For force-refresh, edit the row in the admin UI directly.