As a user I want a help page on the site so I can learn how to use the archive and share the guidance with family members before a scanning session #70

New Issue

marcel · 2026-03-25T18:58:47+01:00

marcel commented

2026-03-25 18:58:47 +01:00

Background

Family members who scan documents need to know two things before they start: how to name their files so metadata is auto-filled, and how to use the collaboration features once documents are in the archive. A /help page on the site serves both needs — it's always up to date, can be opened on the phone during a scanning session, and can be printed or linked in an email instead of attaching a static document.

User Journey

A family member is about to scan a box of letters. They receive a link to /help (or find the "Help" link in the nav). The page is structured into short sections they can read top to bottom or jump to. It covers:

Uploading documents — how to use the drop zone, that multiple files can be dropped at once, that files can be enriched later
Filename conventions — which naming patterns trigger auto-fill, with copy-pasteable examples and a short explanation of each field that gets extracted
The enrichment queue — what "Needs metadata" means and how to work through it efficiently
Conversations — how to start a thread on a document, reply, and @-mention other family members
Annotations — how to draw a rectangle annotation on a PDF, add a comment, and reply to others

The page is print-friendly: clean typography, no sidebars, a "Print" link at the top. Each section has a short anchor link so individual sections can be linked directly from the UI (e.g. the drop zone hint links to #filename-conventions).

E2E Scenarios

Scenario: Help page is reachable from the nav
  Given I am on any page
  When I click the "Help" link in the navigation
  Then I am taken to /help

Scenario: All major sections are present
  Given I am on /help
  Then I see a section about uploading and the drop zone
  And I see a section about filename conventions with examples
  And I see a section about the enrichment queue
  And I see a section about conversations
  And I see a section about annotations

Scenario: Direct link to a section works
  Given I navigate to /help#filename-conventions
  Then the filename conventions section is visible and scrolled into view

Implementation notes

Static SvelteKit route — no server load function, no backend changes.
Content is written directly in the .svelte file (no CMS needed at this scale).
The page does not need i18n in the first version — German only is fine.
A "Help" link should be added to the global nav (low-visibility, e.g. a ? icon or a text link in the footer area of the header).
Inline hints in the drop zone (#66) and filename parser (#69) should link to the relevant anchors on this page.
Print stylesheet: hide the nav header and any interactive chrome, keep only the content.

Content outline

# Familienarchiv — Hilfe

## Dokumente hochladen
- Drop zone erklären
- Mehrere Dateien auf einmal
- Danach anreichern

## Dateinamen-Konventionen
Wenn du deine Scans nach diesem Muster benennst, füllt das Archiv Datum und Absender automatisch aus:

  2024-03-15_Hans_Mueller.pdf   → Datum: 15.03.2024, Absender: Hans Mueller
  20240315_Oma.pdf              → Datum: 15.03.2024, Name: Oma
  Hans_Mueller.pdf              → Name: Hans Mueller (kein Datum)

## Fehlende Metadaten ergänzen (Warteschlange)
- Was bedeutet "Metadaten fehlen"
- Wie man die Warteschlange durcharbeitet

## Gespräche
- Wie man eine Unterhaltung zu einem Dokument startet
- Wie man antwortet

## Annotationen
- Wie man den Annotationsmodus aktiviert
- Rechteck zeichnen
- Kommentar hinzufügen und antworten

Related: #66 (drop zone links here), #67 (enrichment queue links here), #69 (filename parser links here)

## Background Family members who scan documents need to know two things before they start: how to name their files so metadata is auto-filled, and how to use the collaboration features once documents are in the archive. A `/help` page on the site serves both needs — it's always up to date, can be opened on the phone during a scanning session, and can be printed or linked in an email instead of attaching a static document. ## User Journey A family member is about to scan a box of letters. They receive a link to `/help` (or find the "Help" link in the nav). The page is structured into short sections they can read top to bottom or jump to. It covers: 1. **Uploading documents** — how to use the drop zone, that multiple files can be dropped at once, that files can be enriched later 2. **Filename conventions** — which naming patterns trigger auto-fill, with copy-pasteable examples and a short explanation of each field that gets extracted 3. **The enrichment queue** — what "Needs metadata" means and how to work through it efficiently 4. **Conversations** — how to start a thread on a document, reply, and @-mention other family members 5. **Annotations** — how to draw a rectangle annotation on a PDF, add a comment, and reply to others The page is print-friendly: clean typography, no sidebars, a "Print" link at the top. Each section has a short anchor link so individual sections can be linked directly from the UI (e.g. the drop zone hint links to `#filename-conventions`). ## E2E Scenarios ``` Scenario: Help page is reachable from the nav Given I am on any page When I click the "Help" link in the navigation Then I am taken to /help Scenario: All major sections are present Given I am on /help Then I see a section about uploading and the drop zone And I see a section about filename conventions with examples And I see a section about the enrichment queue And I see a section about conversations And I see a section about annotations Scenario: Direct link to a section works Given I navigate to /help#filename-conventions Then the filename conventions section is visible and scrolled into view ``` ## Implementation notes - Static SvelteKit route — no server load function, no backend changes. - Content is written directly in the `.svelte` file (no CMS needed at this scale). - The page does not need i18n in the first version — German only is fine. - A "Help" link should be added to the global nav (low-visibility, e.g. a `?` icon or a text link in the footer area of the header). - Inline hints in the drop zone (#66) and filename parser (#69) should link to the relevant anchors on this page. - Print stylesheet: hide the nav header and any interactive chrome, keep only the content. ## Content outline ``` # Familienarchiv — Hilfe ## Dokumente hochladen - Drop zone erklären - Mehrere Dateien auf einmal - Danach anreichern ## Dateinamen-Konventionen Wenn du deine Scans nach diesem Muster benennst, füllt das Archiv Datum und Absender automatisch aus: 2024-03-15_Hans_Mueller.pdf → Datum: 15.03.2024, Absender: Hans Mueller 20240315_Oma.pdf → Datum: 15.03.2024, Name: Oma Hans_Mueller.pdf → Name: Hans Mueller (kein Datum) ## Fehlende Metadaten ergänzen (Warteschlange) - Was bedeutet "Metadaten fehlen" - Wie man die Warteschlange durcharbeitet ## Gespräche - Wie man eine Unterhaltung zu einem Dokument startet - Wie man antwortet ## Annotationen - Wie man den Annotationsmodus aktiviert - Rechteck zeichnen - Kommentar hinzufügen und antworten ``` Related: #66 (drop zone links here), #67 (enrichment queue links here), #69 (filename parser links here)

marcel referenced this issue

2026-03-25 19:27:36 +01:00

As a user I want to @mention other users in comments so they are notified and linked to their profile #72

marcel added the notification label 2026-03-25 20:30:06 +01:00

marcel commented

2026-03-27 19:03:01 +01:00

UX Review — @leonievoss

Overall: well-scoped and independent of the other notification issues. Two things to nail before implementation.

🔴 High — Print stylesheet must be specified, not implied

The issue mentions "print-friendly" but leaves the stylesheet to the implementer. This will be forgotten. Specify it explicitly:

@media print {
  nav, header, .no-print { display: none; }
  body { font-size: 12pt; line-height: 1.6; }
  a[href]::after { content: " (" attr(href) ")"; font-size: 10pt; }
}

The last rule is important: print-out recipients who receive a physical copy should still be able to see anchor URLs.

🔴 High — `?` icon nav link fails for seniors

The implementation note suggests a ? icon or a text link "in the footer area of the header". An icon-only link violates the redundant cues principle for the 60+ audience — they may not associate ? with Help at all.

Use a visible text link: "Hilfe" with a small ? icon alongside it, not instead of it. Minimum touch target 44×44px. Low visual weight is fine (same style as the subtle action links already in the nav), but the word must be present.

🟡 Medium — Section headings need explicit `id` attributes called out

The spec implies anchor links like #filename-conventions will work, but doesn't state that each <h2> must carry a matching id. Without this, the deep links from the drop zone (#66) and filename parser (#69) will silently land at the top of the page. Add to implementation notes:

Each section heading must be a <h2 id="section-slug"> where the slug matches the anchor used in cross-page links (e.g. id="filename-conventions", id="gespraeche", id="annotationen").

🟡 Medium — Exclude `/help` from Paraglide route generation

The spec says "German only is fine for v1". Add a note that the /help route must be excluded from Paraglide's i18n route generation so it doesn't appear as a missing translation and doesn't throw a build warning for en and es.

✅ What's good

Static SvelteKit route with no server load — correct, no over-engineering.
Anchor links per section — essential, and called out correctly.
Content outline is well-structured for the dual audience (millennials scan, seniors read top-to-bottom).
Linking from inline hints (#66, #69) to specific anchors is the right pattern.

## UX Review — @leonievoss Overall: well-scoped and independent of the other notification issues. Two things to nail before implementation. ### 🔴 High — Print stylesheet must be specified, not implied The issue mentions "print-friendly" but leaves the stylesheet to the implementer. This will be forgotten. Specify it explicitly: ```css @media print { nav, header, .no-print { display: none; } body { font-size: 12pt; line-height: 1.6; } a[href]::after { content: " (" attr(href) ")"; font-size: 10pt; } } ``` The last rule is important: print-out recipients who receive a physical copy should still be able to see anchor URLs. ### 🔴 High — `?` icon nav link fails for seniors The implementation note suggests a `?` icon or a text link "in the footer area of the header". An icon-only link violates the redundant cues principle for the 60+ audience — they may not associate `?` with Help at all. Use a visible text link: **"Hilfe"** with a small `?` icon alongside it, not instead of it. Minimum touch target 44×44px. Low visual weight is fine (same style as the subtle action links already in the nav), but the word must be present. ### 🟡 Medium — Section headings need explicit `id` attributes called out The spec implies anchor links like `#filename-conventions` will work, but doesn't state that each `<h2>` must carry a matching `id`. Without this, the deep links from the drop zone (#66) and filename parser (#69) will silently land at the top of the page. Add to implementation notes: > Each section heading must be a `<h2 id="section-slug">` where the slug matches the anchor used in cross-page links (e.g. `id="filename-conventions"`, `id="gespraeche"`, `id="annotationen"`). ### 🟡 Medium — Exclude `/help` from Paraglide route generation The spec says "German only is fine for v1". Add a note that the `/help` route must be excluded from Paraglide's i18n route generation so it doesn't appear as a missing translation and doesn't throw a build warning for `en` and `es`. ### ✅ What's good - Static SvelteKit route with no server load — correct, no over-engineering. - Anchor links per section — essential, and called out correctly. - Content outline is well-structured for the dual audience (millennials scan, seniors read top-to-bottom). - Linking from inline hints (#66, #69) to specific anchors is the right pattern.

marcel commented

2026-03-27 19:13:40 +01:00

QA Review — @saraholt

Simple feature, but two things will silently break if not encoded as tests.

🟡 Section anchors must be verified by a test, not just specified

Leonie flagged that each <h2> must carry a matching id attribute, otherwise the deep links from #66 and #69 silently land at the top of the page. Encode this as an E2E test so it can't break invisibly:

test('all section anchors are reachable via URL fragment', async ({ page }) => {
  const sections = [
    'dokumente-hochladen',
    'dateinamen-konventionen',
    'fehlende-metadaten',
    'gespraeche',
    'annotationen'
  ];

  for (const anchor of sections) {
    await page.goto(`/help#${anchor}`);
    await expect(page.locator(`#${anchor}`)).toBeVisible();
  }
});

Adjust the slugs to match whatever id values are used in the implementation — the test enforces the contract.

🟡 Nav link reachability — add to E2E suite

The issue spec lists this as an E2E scenario. It should be written explicitly:

test('help page is reachable from the global nav', async ({ page }) => {
  await page.goto('/');
  await page.getByRole('link', { name: /hilfe/i }).click();
  await expect(page).toHaveURL('/help');
  await checkA11y(page);
});

checkA11y on the help page is low-cost and will catch Leonie's concern about the ? icon — if the nav link is icon-only without accessible text, axe will flag it.

🟡 Print stylesheet — manual checklist in the PR

Automated print testing in Playwright exists but is fragile and not worth the setup overhead for a static content page. Flag it as a manual checklist item in the PR description:

- [ ] Print preview verified in Chrome: nav hidden, content readable, anchor URLs visible in printed links
- [ ] Print preview verified on mobile (Safari iOS): same checks

This makes it a conscious sign-off, not an assumption.

🟡 Paraglide exclusion — add a build check

Leonie noted the /help route must be excluded from Paraglide's i18n route generation. Verify this doesn't regress:

npm run build 2>&1 | grep -i "missing translation" | grep "help"
# Should produce no output

Add this as a step in the CI integration-tests job so a future Paraglide config change doesn't silently reintroduce the warning.

✅ What's solid

Static SvelteKit route with no server load function — correct, no over-engineering
Content outline is well-structured; covers the dual audience (scan top-to-bottom vs. skip to section)
Anchor links per section called out explicitly in the spec

## QA Review — @saraholt Simple feature, but two things will silently break if not encoded as tests. --- ### 🟡 Section anchors must be verified by a test, not just specified Leonie flagged that each `<h2>` must carry a matching `id` attribute, otherwise the deep links from #66 and #69 silently land at the top of the page. Encode this as an E2E test so it can't break invisibly: ```typescript test('all section anchors are reachable via URL fragment', async ({ page }) => { const sections = [ 'dokumente-hochladen', 'dateinamen-konventionen', 'fehlende-metadaten', 'gespraeche', 'annotationen' ]; for (const anchor of sections) { await page.goto(`/help#${anchor}`); await expect(page.locator(`#${anchor}`)).toBeVisible(); } }); ``` Adjust the slugs to match whatever `id` values are used in the implementation — the test enforces the contract. --- ### 🟡 Nav link reachability — add to E2E suite The issue spec lists this as an E2E scenario. It should be written explicitly: ```typescript test('help page is reachable from the global nav', async ({ page }) => { await page.goto('/'); await page.getByRole('link', { name: /hilfe/i }).click(); await expect(page).toHaveURL('/help'); await checkA11y(page); }); ``` `checkA11y` on the help page is low-cost and will catch Leonie's concern about the `?` icon — if the nav link is icon-only without accessible text, axe will flag it. --- ### 🟡 Print stylesheet — manual checklist in the PR Automated print testing in Playwright exists but is fragile and not worth the setup overhead for a static content page. Flag it as a **manual checklist item** in the PR description: ``` - [ ] Print preview verified in Chrome: nav hidden, content readable, anchor URLs visible in printed links - [ ] Print preview verified on mobile (Safari iOS): same checks ``` This makes it a conscious sign-off, not an assumption. --- ### 🟡 Paraglide exclusion — add a build check Leonie noted the `/help` route must be excluded from Paraglide's i18n route generation. Verify this doesn't regress: ```bash npm run build 2>&1 | grep -i "missing translation" | grep "help" # Should produce no output ``` Add this as a step in the CI integration-tests job so a future Paraglide config change doesn't silently reintroduce the warning. --- ### ✅ What's solid - Static SvelteKit route with no server load function — correct, no over-engineering - Content outline is well-structured; covers the dual audience (scan top-to-bottom vs. skip to section) - Anchor links per section called out explicitly in the spec

marcel closed this issue

2026-03-28 16:08:37 +01:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: marcel/familienarchiv#70

As a user I want a help page on the site so I can learn how to use the archive and share the guidance with family members before a scanning session #70

Background

User Journey

E2E Scenarios

Implementation notes

Content outline

UX Review — @leonievoss

🔴 High — Print stylesheet must be specified, not implied

🔴 High — ? icon nav link fails for seniors

🟡 Medium — Section headings need explicit id attributes called out

🟡 Medium — Exclude /help from Paraglide route generation

✅ What's good

QA Review — @saraholt

🟡 Section anchors must be verified by a test, not just specified

🟡 Nav link reachability — add to E2E suite

🟡 Print stylesheet — manual checklist in the PR

🟡 Paraglide exclusion — add a build check

✅ What's solid

🔴 High — `?` icon nav link fails for seniors

🟡 Medium — Section headings need explicit `id` attributes called out

🟡 Medium — Exclude `/help` from Paraglide route generation