89 lines
4.9 KiB
Markdown
89 lines
4.9 KiB
Markdown
# 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
|
||
```yaml
|
||
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.
|