fotospiel-app/docs/help

Help System Blueprint

This folder defines the bilingual help center that serves both guest app users and customer admins. It stores the source Markdown, translation metadata, and the publishing workflow that feeds the in-app help experiences.

Goals

• Give each audience (Guests vs. Admins) tailored, task-based documentation in German and English.
• Keep a single Git-tracked source of truth with translation status and review history.
• Deliver lightweight, searchable payloads to both apps (offline capable for guests, richer navigation for admins).
• Allow non-developers to contribute through Filament while still publishing Markdown to the repo.

Directory Layout

docs/help/
├── README.md
├── en/
│   ├── admin/
│   │   ├── index.md
│   │   └── …
│   ├── guest/
│   │   ├── index.md
│   │   └── …
│   └── templates/
│       └── article.md
└── de/
    ├── admin/
    ├── guest/
    └── templates/

• English and German live under their respective locale folders, which keeps slugs unique for the Docusaurus build (/help/en/admin/..., /help/de/guest/...).
• Inside each locale folder, article filenames match their slug (e.g., post-event-wrapup.md). Paired locales keep the same slug and metadata.
• Every article includes the YAML front matter shown below so the apps and Filament know how to render status, owners, etc.

Front Matter Contract

title: "Getting Started"
locale: en
slug: getting-started
audience: guest               # guest | admin | shared
summary: "Install the guest app and join an event in under a minute."
version_introduced: 2025.4
requires_app_version: "^3.2.0" # optional semver filter for the apps
status: published              # draft | review | published
translation_state: aligned     # draft | needs_update | aligned
last_reviewed_at: 2025-01-10
owner: cx-team@fotospiel.app   # rotational owner or team list
related:
  - slug: offline-sync
  - slug: privacy-basics

• translation_state tracks whether the paired locale matches the canonical source. CI should warn when one locale lags.
• requires_app_version lets an app hide docs when the installed build lacks that feature.

Authoring & Translation Workflow

1. Plan – open an issue referencing the article slug and target locales.
2. Draft – copy the locale template, write the content, keep paragraphs short for mobile.
3. Review – tech review (feature owner) + linguistic review (native speaker). Update status and last_reviewed_at.
4. Translate – for the paired locale, mark translation_state accordingly and link PRs together.
5. Publish – merge to main. A CI job should rebuild the Markdown cache and push structured JSON to storage (e.g., S3 or Redis) consumed by Laravel.

Tip: prefer screenshots only in admin docs; guest docs focus on concise steps + illustrations already shipped in the app.

Delivery Architecture

• Source of truth: Markdown in this folder.
• Processing: an Artisan job (help:sync) parses Markdown via league/commonmark, validates front matter, generates per-locale JSON bundles, and stores them under storage/app/help/<audience>/<locale>.json.
• API:
  • GET /api/help?audience=guest&locale=de → paginated list with title, summary, slug, version_introduced, updated_at.
  • GET /api/help/{slug} → full article body + related slugs.
  • Guests access anonymously; admins require auth middleware (so we can show restricted docs).
• Caching:
  • Cache list + article JSON for 10 minutes in Redis; bust cache whenever the sync job runs.
  • Guest app prefetches JSON during first online session and stores it in IndexedDB for offline reading.
  • Admin app keeps only recent items client-side but relies on online search for canonical versions.
• Search:
  • During sync, build Lunr/MiniSearch indexes per audience/locale and ship them to the app bundles for offline search.

Contextual Access

• Guest App: add ? entry points (floating button, settings, upload errors) that deep-link to slugs. Offer article-level language toggles.
• Admin App / Filament: show contextual “Need help?” links near complex forms, routing to /help/{slug} in an in-app modal. Provide a global Help center route with sidebar nav and server-driven breadcrumbs.
• Standalone Web: optional /help public site generated from the same Markdown using Vite/React and server-side rendering for SEO.

Governance & Backlog

• Track work in bd issues and link them to article slugs.
• Add CI checks:
  • Ensure every .en.md file has a matching .de.md file with equal slug/version_introduced.
  • Validate required front matter keys.
• Future enhancements:
  • Integrate with Paddle customer portal for billing-related admin help.
  • Add analytics event (non-PII) for article views through the app to measure usefulness.