Przejdź do głównej zawartości

Docs authoring guide

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

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.
  5. Screenshot - wymagane oba ujęcia:
    • ...--desktop.png (1440x900)
    • ...--mobile.png (390x844, prawdziwy mobile z hamburgerem)
  6. Steps - konkretne etykiety UI. Pod każdym krokiem embed anotowanych screenów desktop + mobile (...--step-N--desktop.png / ...--step-N--mobile.png) ze strzałką. Generuj: npm run capture:steps potem npm run embeds:steps.
  7. Fields and actions - list real controls.
  8. Common mistakes - cross-screen failures users hit.
  9. Related - markdown links to hubs, how-tos, and screens.

Dialog pages also need Dialog appears when and prefer 2-3 sequence shots.

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

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, and dialogs.
  3. Edit the MDX under docs-site/docs/.
  4. Set status: reviewed.
  5. Run npm run generate (merge-safe - keeps reviewed body) then npm run check-coverage.
  6. Capture shots: npm run capture (throttled) or npm run capture:dialogs.

Commands​

  • npm run promote-reviewed - bulk promote from guidance map (do not run with FORCE after hand edits you want to keep unless filtered).
  • CAPABILITY_FILTER=learners npm run promote-reviewed - one capability.
  • Never FORCE_STUBS=1 or enrich FORCE=1 after reviewed content exists.

ASCII only​

Use hyphen -, never Unicode em dash.

Interaction Fidelity (fidelity: interaction)​

Poziom IF dokumentuje otwarte listy, opcje, dialogi i strzalki (jak Printouts - Report cards - Academic year). Pelna specyfikacja: angielski Docs authoring guide.

Komendy: npm run capture:interaction, npm run inventory:interaction, npm run pdf:if-pack.