Skip to main content

Maintain this manual

The source lives in the application repository so a behavior change and its documentation can land together. Generated screenshots live in the sibling lotti-docs repository and are never committed to the application tree.

Edit prose​

  1. Edit or add the English MDX file under docs-site/docs.
  2. Update the matching file for every published locale under docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current.
  3. Add a new page to docs-site/sidebars.ts.
  4. Update docs-site/metadata/features.json when coverage changes.
  5. Update the matching entries in docs-site/metadata/surface-inventory.json. A surface becomes verified only when its current production UI, prose, and screenshot coverage have all been reviewed.
  6. Run make manual_check.
  7. Review the production build locally with make manual_serve, including the language selector and every localized route.

Validation requires every published translation tree to contain the same page paths as the English source tree. It also rejects translated page bodies that are identical to English, so new pages cannot quietly ship as untranslated copies. The public English URLs remain unchanged; other languages are published below their own versioned locale prefix.

Keep the coverage inventory authoritative​

The inventory defines the V1 English-manual boundary: every Beamer page, every Settings V2 leaf or editor, and every major workflow that creates or materially changes data or cross-cutting configuration. Each entry records its owning source file and a source-text anchor. Validation fails if either disappears, which forces a route or UI change to update the manual audit instead of leaving an invisible stale row.

Coverage states have deliberately strict meanings:

  • Planned means the surface is known but still lacks complete coverage.
  • Documented means useful prose exists, but current production screenshots or an end-to-end accuracy review are still missing.
  • Verified means the relevant feature page is verified and backed by registered production screenshots.

Run npm --prefix docs-site run coverage:complete for the release gate. It fails until every inventoried surface is verified; ordinary incremental manual builds continue to report the remaining counts without blocking topic-sized commits.

Add a screenshot case​

  1. Add or reuse a deterministic Flutter screenshot harness.
  2. Register the case and its four source images in docs-site/metadata/screenshot-cases.json.
  3. Put visible fixture copy behind manualScreenshotText(...) for every supported locale when it is not already provided by the app localization files.
  4. Capture every locale into ../lotti-docs; never into this repository.
  5. Generate and validate the media manifest.
  6. Reference the case with <ManualScreenshot caseId="…" alt="…" /> on every language page.

Every app screenshot in an authored page must use ManualScreenshot. Direct links to old lotti-docs images fail manual validation because they cannot follow the global Mobile/Desktop choice or the manual's light/dark theme.

Every automated case must provide mobile-light, mobile-dark, desktop-light, and desktop-dark variants in every published locale. The manual component chooses the matching language and theme. Changing Mobile/Desktop on any image updates every screenshot immediately and persists across pages and open manual tabs.

Publish a release​

Manual source is not copied for every app version. The app release tag already preserves its exact source. CI checks out that tag, builds with MANUAL_VERSION=<version>, and publishes an immutable static directory. The release dropdown is a small manifest of those directories.