Voeg eindgebruiker-documentatie toe aan een feature

Aan het einde van deze gids heeft een feature in apps/frontend/src/app/features/ of apps/api/src/modules/ een userdocs/index.md die binnen 2 minuten na merge naar main als artikel in de Freescout Knowledge Base verschijnt onder mailbox 1.

Voorwaarden:

  • De feature is user-facing (een gebruiker, beheerder of admin ziet het gedrag).
  • Je werkt in een Claude Code sessie binnen tapster-backend.
  • De freescout-sync.yml workflow staat actief op main (na fase 3 merge).

Voor het verschil tussen eindgebruiker-documentatie en interne documentatie, zie docs/CONTRIBUTING-DOCS.md. Voor de volledige conventie (frontmatter-velden, stijlregels), zie apps/frontend/AGENTS.md.

Stappen

1. Roep de slash-command aan

Vanuit Claude Code, met het pad naar de feature-folder:

/generate-userdocs apps/frontend/src/app/features/<scope>/<feature>

Voor een backend-module:

/generate-userdocs apps/api/src/modules/<module>

De slash-command leest routes, page-templates, components en i18n; past de Tapster stijlregels toe (Nederlands, geen em-dashes, korte zinnen, tweede persoon); en schrijft userdocs/index.md met geldige frontmatter.

2. Review de gegenereerde tekst

Open het bestand dat de agent heeft geschreven. Controleer:

  • Elke UI-label klopt met wat in de templates staat (de agent mag niets verzinnen, maar het is jouw werk om dat te bevestigen).
  • De audience klopt: gebruiker, beheerder of admin (matched met de feature-folder — zie tabel hieronder).
  • category heeft het patroon Gebruiker > ..., Beheerder > ... of Admin > ... overeenkomstig de audience.
Feature-folder audience category-prefix
apps/frontend/src/app/features/user/... gebruiker Gebruiker > ...
apps/frontend/src/app/features/backoffice/... beheerder Beheerder > ...
apps/frontend/src/app/features/admin/... admin Admin > ...
apps/frontend/src/app/features/global/... afhankelijk van wie het ziet matchend met audience
apps/api/src/modules/... afhankelijk van wie het raakt matchend met audience
  • status staat op draft zolang je nog niet zeker bent. Op published zodra de tekst geschikt is voor live KB.

Pas tekstuele dingen aan waar nodig. Behoud freescout_article_id, freescout_category_id, slug en content_hash zoals de agent ze heeft achtergelaten (leeg bij nieuwe userdoc, gevuld bij update).

3. Valideer lokaal 

npm run userdocs:validate

Verwacht: ✓ N userdoc(s) valide. Bij een Zod-fout: lees de melding, fix de frontmatter, run opnieuw.

4. Commit en push 

git checkout -b feat/userdocs-<feature-naam>
git add apps/frontend/src/app/features/<scope>/<feature>/userdocs/
git commit -m "docs(userdocs): voeg gids voor <feature-naam>"
git push -u origin feat/userdocs-<feature-naam>

De PR wordt automatisch geopend. CI-check userdocs-check valideert je frontmatter; als productie-code is gewijzigd zonder bijbehorende userdocs-mutatie, plaatst de bot een waarschuwingscomment.

5. Merge naar main

Na review en groene checks: mergen. Daarna:

  • freescout-sync.yml triggert binnen seconden.
  • Sync rendert je markdown naar HTML, regelt category-pad (recursief, idempotent), POSTet het artikel naar Freescout KB onder mailbox 1.
  • Bot commit op main: chore(userdocs): sync to freescout KB [skip ci] met de bijgewerkte frontmatter (freescout_article_id, freescout_category_id, content_hash).
  • Bij een volgende merge zonder content-wijziging skipt de sync via content-hash.

Verifieer in Freescout admin onder Knowledge Base dat het artikel verschijnt.

Wanneer hoort er een userdoc bij een PR?

PR-inhoud userdoc nodig?
Nieuwe user-facing feature Ja
Wijziging in bestaand UI-gedrag dat een gebruiker/beheerder/admin ziet Ja, update bestaande
Pure refactor zonder UI-impact Nee
Pure styling-tweak (kleuren, padding) Nee
Bug-fix die voorheen gedocumenteerd gedrag herstelt Optioneel, alleen als de oude userdoc daadwerkelijk fout was
Nieuwe admin-only feature in apps/api/src/modules/ Ja als een beheerder direct met het proces interacteert
Pure infrastructuur (queues, scim-sync) Nee

Twijfel je? Lees de bestaande apps/frontend/src/app/features/user/zoeken/userdocs/index.md als referentie.

Een userdoc weghalen of intrekken

Wil je een artikel intrekken (bijvoorbeeld omdat de feature is verwijderd)? Zet status: draft in de frontmatter en mergeer. De volgende sync detecteert de status-flip en doet DELETE op het artikel in Freescout. Het bronbestand blijft in de repo staan voor traceability.

Bij meer dan 5 verwijderingen in één sync-run faalt de workflow voor de zekerheid. Override met workflow_dispatch en confirm_deletes: true als je inderdaad een grote opruimactie doet.

Een korte voorbeeld-prompt voor je AI-agent

“Lees apps/frontend/AGENTS.md sectie ‘Eindgebruiker-documentatie (userdocs)’ en de slash-command in .claude/commands/generate-userdocs.md. Genereer vervolgens een userdoc voor apps/frontend/src/app/features/<scope>/<feature> volgens die conventie. Rapporteer welke UI-acties je hebt afgeleid en welke delen menselijke review nodig hebben.”

De agent volgt dan automatisch de juiste folder-conventie, stijl en frontmatter.

Verwante documentatie