update-user-guide

name

update-user-guide

description

Update or extend the end-user documentation in `docs/user-guide/` after shipping a user-facing feature. Use when adding a new workflow, changing user-facing behavior in an existing workflow, expanding what a persona can do, or fulfilling/removing a "Coming soon" item. Targets the per-module folder under `docs/user-guide/<module>/` with its README + `workflows/` pages, and follows the templates in `docs/user-guide/_template/`.

Update User Guide

End-user docs live in docs/user-guide/<module>/ and are published to the GitHub Pages wiki on merge to dev. Update them whenever a user-facing change ships.

When this skill applies

Trigger this skill when the change is visible to a user in the UI:

• New context-menu item, button, dialog, page, or wizard.
• New / changed validation rule, error message, or constraint a user can hit.
• Expanded or contracted capability of a persona (Viewer / Editor / Admin).
• Fulfilled or cancelled item from a module's Coming soon list.
• New permission gate that changes who can do what.

Skip this skill for purely internal refactors with no UI/behavior change. Those go to the update-technical-docs skill.

Files you will touch

docs/user-guide/
├── README.md                        — module status table (only on first doc of a module, or status flip)
├── _template/
│   ├── README.template.md           — copy this when documenting a new module
│   └── workflow.template.md         — copy this when adding a new workflow
└── <module>/
    ├── README.md                    — module overview, personas, key concepts, workflow links, Coming soon
    └── workflows/
        └── <new-or-changed>.md      — one page per user-facing workflow

Workflow

1. Map the change to its module + persona

• Which module folder owns this? (systemHierarchy/, catalogue/, orders/, …)
• Which persona gained/lost capability? (Viewer / Editor / Admin — see the persona table in the module's README.md)
• Does this fulfill a 🔮 Coming soon bullet? If yes, plan to delete that bullet.

If the affected module has no folder yet, copy _template/README.template.md to <module>/README.md and bump the row in the top-level README.md status table from 🚧 to 📝.

2. Decide: new workflow page, or edit existing one?

• New workflow page — when the change introduces a distinct user task (e.g. "Creating systems", "Bulk-exporting orders"). One workflow = one page.
• Edit existing page — when the change adjusts an already-documented flow (e.g. new field on an existing dialog, new validation rule, scope change to who can do it).

If editing an existing page, also re-read the module README.md — persona capabilities and the workflow link's one-line summary often need a touch.

3. Author following the templates

For a new workflow, start from docs/user-guide/_template/workflow.template.md. Required sections in order:

Section	Required?	Notes
# <Workflow title>	yes	Imperative — "Creating systems", "Copying systems"
## What this is for	yes	1-3 sentences. Lead with the user's intent + a key constraint.
## Who can do this	yes	Persona badge (✏️ / 👁️) + required role(s). Add 🔮 if Phase 1/2 changes the gate.
## Prerequisites	yes	Where the user must be, key concepts to know — link to README.
## Steps	yes	Numbered. Bold-led instruction sentence per step, then detail. [SCREENSHOT PLACEHOLDER: <what should be visible>] between steps where UI state matters. [VIDEO PLACEHOLDER: <duration + scenario>] at the end.
## What gets <verb>ed	optional	Use when the effect is non-obvious or partial — ✅/❌ bullets.
## Limitations	optional	Hard constraints (scope, depth caps, atomicity).
## Tips & gotchas	optional	Real tips/edge cases only. Don't pad.
## Related	yes	Sibling workflow links + cross-module pointers via the user-guide index.

For a new module, start from docs/user-guide/_template/README.template.md. Required sections: Overview, Access & Responsibilities (today + 🔮 callouts), Key concepts, Layout, Common workflows (links), Coming soon, Data model reference (engineer-only block), Language.

4. Authoring rules

• Audience is hybrid — engineers and business users. Engineering parts may use precise terms (entity names, relationship names from the user's vocabulary); business parts stay plain.
• Never reference code paths (.tsx, hook names, file paths). Code-level details go to docs/technical/.
• Match UI labels verbatim to the EN locale at src/i18n/src/locale/en.ts. Wrap them in bold or italic exactly as the user sees them.
• Placeholders, not images. Every [SCREENSHOT PLACEHOLDER: …] must describe what should be visible — never a bare [SCREENSHOT]. Same for [VIDEO PLACEHOLDER: …] (include duration + scenario).
• Tables for option matrices. When a workflow has a parent→child rule, an allowed-combination matrix, or a What gets copied / What does NOT block — use a table or paired ✅/❌ lists.
• Cross-link, don't duplicate. Term definitions live in the module README's Key concepts. Link there, don't redefine.
• English only. The app is English-only today.

5. Update the module README.md if needed

After authoring the workflow, check the module README for:

• Persona capabilities row — if the new workflow added a capability for a persona, append it to the Can do cell (the verb form, comma-separated). Example: copy/paste shipped → add "copy systems" to Editor's capabilities.
• Common workflows list — add a bullet linking the new workflow file with its one-line summary.
• Coming soon list — if this change fulfilled a 🔮 bullet, delete that bullet entirely. Don't strikethrough.
• Layout / Key concepts — usually not needed, but if the change introduces a new term or panel, update accordingly.

6. Verification

• Open every link in the changed/new files locally — broken relative paths are the most common mistake.
• Grep the rest of docs/user-guide/ for the old behavior if you removed/replaced a feature. Other workflow pages may reference it.
• If you bumped a row in the top-level docs/user-guide/README.md status table, double-check the link target exists.

7. Commit

Commit message format: docs(<module>): <verb> <workflow> workflow. Examples:

• docs(systemHierarchy): document Create Subsystem flow
• docs(orders): update delivery flow for partial shipments
• docs(catalogue): drop 'Coming soon' bulk-import bullet (feature shipped)

Glossary alignment

Names must match docs/CONTEXT.md and the relevant docs/technical/<feature>.md page. If you're using a term that isn't already in CONTEXT.md, either pick an existing one or update the glossary in the same PR as the user-guide change.

Common pitfalls

• Leaving the Coming soon bullet after shipping the feature. Always remove it.
• Skipping the persona table update. A new workflow almost always changes what at least one persona can do.
• Linking to a workflow file that doesn't exist yet. Create the file before the link.
• Inventing UI labels. Open src/i18n/src/locale/en.ts and copy the exact string.
• Bare screenshot placeholders. Always describe what the screenshot should show.
• Mixing engineering details in. No file paths, no hook names, no GraphQL fragments — those belong in docs/technical/.