Docs authoring guide

How to write and keep E-School user docs accurate to the live product.

Gold page shape (reviewed)

1. One or two sentences for the page purpose.
2. Who can use this - roles.
3. Path - exact app route.
4. Dependencies - named upstream screens (or explicit - None when truly none).
5. Screenshot - both desktop and mobile embeds are required:
   • ...--desktop.png (1440x900)
   • ...--mobile.png (390x844, real mobile chrome with hamburger - not desktop UI squeezed)
6. Steps - operator procedure with concrete UI labels (buttons, tabs, filters). Never invent. Never use formula skeletons. Under each numbered step embed annotated desktop + mobile shots (...--step-N--desktop.png / ...--step-N--mobile.png) with a red arrow on the control being used. Generate with npm run capture:steps then npm run embeds:steps.
7. Fields and actions - list real controls (deduplicated).
8. Common mistakes - cross-screen failures users hit.
9. Related - markdown links to hubs, how-tos, and screens.

Optional: one short Mobile: note only when the mobile layout truly differs (not a copy-paste about toolbars wrapping).

Dialog pages also need Dialog appears when and prefer 2-3 sequence shots (each sequence step: desktop + mobile).

How-to journeys: each key operation in the flow should embed desktop + mobile shots (not only one hero image).

Interaction Fidelity (fidelity: interaction)

reviewed alone is not enough for operator-grade paths. Pages in an Interaction Fidelity (IF) wave add frontmatter fidelity: interaction and must document open UI states, not only closed screenshots.

Use this level when the operator must open a dropdown, menu, filter popover, dialog, or hub card - the same depth as the Printouts hub → Report cards → Academic year option examples.

Required on every IF screen

Requirement	Screenshot must show
Navigation	Arrow on sidebar item or hub card (for example Printouts → Report cards)
Closed control	Arrow on the trigger (dropdown, Filters, overflow, Configure columns)
Open state	Same control expanded; list or popup visible
Option	Arrow on a specific list option (for example 2026), not only the closed field
CTA	Arrow on the action button (Generate / Save / Print / Release)
Dialog / wizard	Sequence of 2-3 frames: open → fill → confirm (desktop + mobile)
Empty / gate	Real empty state plus what to fix upstream - do not fake a full table

Banned for IF: one hero PNG plus vague “pick year and term” with no open-list frame.

Extra MDX sections (IF)

1. Controls inventory - every visible control with type: button, select, menu, dialog, tab, table-action, link-card.
2. Interaction path - numbered steps with one UI target per step. Under each step embed:
   • ...--if-N--desktop.png
   • ...--if-N--mobile.png
3. Options - for each critical select/menu, list live options (or note “depends on school seed”) and point critical choices with dedicated IF frames.

Keep Steps only as a short summary, or replace the operator procedure entirely with Interaction path. check-coverage accepts either ## Steps or ## Interaction path for reviewed pages; IF pages must include Interaction path, Controls inventory, and matching --if-N-- embeds.

Scenario files

Each IF module has a YAML scenario under docs-site/interaction-paths/{module-id}.yaml (kebab file name matching the doc slug, for example admin-report-cards.yaml).

Supported step actions:

• goto - navigate to a route
• click - click button/link/tab by label
• openSelect - open a combobox/select by field label
• pointOption - point the red arrow at a list option (does not have to click unless select: true)
• openMenu - open an overflow / Filters / Configure menu
• openDialog - click a control that opens a dialog, then wait for dialog
• screenshot - capture annotated frame (implicit after point/open actions when shot: true)

Capture with npm run capture:interaction then npm run embeds:interaction.

Wave rollout

1. Gold path: Printouts hub + Report cards (template for all later waves).
2. School Admin modules.
3. Other school roles (shared routes link to the canonical page).
4. Landing (marketing).
5. PDF packs generated from the same IF assets.

Banned template phrases

Do not use:

• Use the primary actions on this screen
• Review the page purpose:
• When finished, follow **Related**
• Complete the primary action described in the product UI
• Confirm the page heading matches
• Primary actions on this screen
• Use the live tabs/sections
• verify the next screen in Related before telling users
• If the view is empty, check class/term/stream filters and Related dependencies
• Mobile: toolbar may wrap; open Filters before looking for missing columns

npm run check-coverage fails if these appear on draft/reviewed pages.

Workflow (live UI)

1. Open the screen in the local demo as the correct role.
2. List visible buttons, tabs, filters, dialogs, and every select/menu that must open.
3. Edit the MDX under docs-site/docs/.
4. Set status: reviewed and, for IF waves, fidelity: interaction.
5. Author interaction-paths/{slug}.yaml for open-state shots.
6. Capture: npm run capture / npm run capture:dialogs / npm run capture:interaction (throttled logins; reuse session cookies).
7. Ensure embeds: npm run embeds / npm run embeds:interaction then REQUIRE_RELEASE=1 npm run check-coverage.
8. Sync Polish under i18n/pl/... after English gold edits.

Commands

• npm run embeds - ensure every screen/dialog MDX embeds desktop + mobile.
• npm run audit:live-ui - compare live labels to MDX.
• npm run capture / npm run capture:dialogs - refresh PNG pairs.
• npm run capture:steps then npm run embeds:steps - per-step annotated desktop + mobile shots.
• npm run capture:interaction then npm run embeds:interaction - IF path shots (open selects, options, dialogs).
• npm run inventory:interaction - crawl live controls into interaction-inventory.json.
• npm run pdf:if-pack - build a client PDF pack from IF pages (Wave 4).
• Never FORCE_STUBS=1 or enrich FORCE=1 after reviewed content exists.
• Do not run promote-reviewed over hand gold pages you want to keep.

ASCII only

Use hyphen -, never Unicode em dash.