schermdocumentatie
Deze map bevat de opgesplitste schermdocumentatie van OefenHub.
Onderdelen
inhoud van deze introductie
In deze introductie staan:
- inleiding
- legenda
- template
1. Inleiding
Deze introductie beschrijft de vaste structuur voor schermdocumentatie binnen OefenHub. Per scherm wordt dezelfde opbouw gebruikt, zodat zichtbare UI-context, velden, waardelagen en trace naar Functioneel Ontwerp en Software Requirements Specification consistent worden vastgelegd.
De documentatie richt zich niet alleen op wat zichtbaar is in de GUI, maar ook op de onderliggende technische en datagerichte verwijzingen. Daardoor kan per scherm onderscheid worden gemaakt tussen zichtbare labels, interne veldnamen, databronnen, waardelagen en lokale schermankers richting centrale SRS-requirements en acceptatiecriteria.
Technische namen in schermdocumentatie, zoals Users, ExerciseRuns, TeacherStudentLevelAccess of UserSettings, duiden schermdatabronnen of logische verwijzingen aan. Zij betekenen niet automatisch dat er een harde database-FK bestaat; technische afdwinging staat in database-informatie en het Technisch Ontwerp.
2. Legenda
Onderstaande codes worden in dit document gebruikt voor schermen en UI-elementen.
| Code | Betekenis |
|---|---|
| SCH | Schermreferentie of scherm-ID op hoofdstuk-/schermniveau. |
| F | Field / invoerveld of uitleesveld. |
| A | Action / gebruikersactie, vaak een link of handeling in de interface. |
| B | Button / knop. |
| T | Table / tabel of tabulaire weergave. |
| S | Section / schermsectie, kaart, paneel of inhoudsblok. |
| TAB | Tab / tabblad of filtertab. |
| M | Message / melding, notificatie, foutmelding of statusmelding. |
| L | Link / navigatielink of tekstlink. |
| MOD | Modal / dialoogvenster of popup. |
| DD | Dropdown / selectielijst of keuzemenu. |
| CHK | Checkbox / selectievakje. |
| RAD | Radiobutton / exclusieve keuzeoptie. |
| COL | Column / tabelkolom. |
| FORM | Form / formulier of submit-context met eigen technische naam, validatie- of submitgedrag. |
3. Template
Gebruik onderstaande vaste opbouw voor ieder scherm. Niet ieder scherm hoeft direct volledig te worden ingevuld, maar de structuur blijft gelijk zodat uitbreiding later eenvoudig is.
3.1 Schermafbeelding
Voeg hier de schermafbeelding of mockup toe. Vermeld bij voorkeur ook de bron, bijvoorbeeld HTML-bestand of designbestand.
3.2 Scherm meta data
Leg basisinformatie vast zoals scherm-ID, schermnaam, doelgroep, bronbestand, mockupversie, processtap, status, route-/autorisatiecontext en eventuele opmerkingen. Gebruik hiervoor onderstaande tabel
| Veld | Waarde |
|---|---|
| Scherm-ID | |
| Schermnaam | |
| Doelgroep / onderdeel | |
| Bronbestand | |
| Mockupversie | |
| Screenshotbestand | |
| Processtap / context | |
| Documentatiestatus | |
| Opmerkingen | |
| Route / URL-patroon | |
| Autorisatie / vereiste rol-context | |
| Primair domeinobject / hoofdentiteit | |
| Gerelateerde schermen / navigatie |
3.3 Functionele beschrijving
Beschrijf doel, gebruikershandeling, context, navigatie, business rules en belangrijkste scenario’s.
3.4 UI-elementen en velddefinities
Werk knoppen, velden, formulieren, tabellen, filters, links en secties uit met een eigen element-ID en betekenis.
Leg waar relevant naast het zichtbare label ook een technische naam vast, zodat UI-gedrag, databinding, testgevallen en latere implementatie eenduidig naar hetzelfde element kunnen verwijzen. Dit geldt ook voor formulieren en andere technische UI-containers die een eigen naam nodig hebben om submit-, validatie- of scriptgedrag te kunnen dragen.
3.5 Waardelagen
Maak onderscheid tussen GUI-verwijzing, zichtbaar label, technische naam, databron, waardebron, datatype, bewerkbaarheid en validaties/regellogica. Leg waar mogelijk de databron vast tot op tabel- en kolomniveau, zodat interpretatieverschillen tussen ontwerp, implementatie en test worden geminimaliseerd.
Naamgeving van technische elementen wordt in dit document vastgelegd in Engelstalige CamelCase-vorm met een hoofdletter aan het begin (UpperCamelCase / PascalCase), bijvoorbeeld StatusDropdown, SearchTicketNumberInput, TicketFilterForm of AssignToUserButton. Dit detailniveau is gewenst voor alle technische UI-elementen die een eigen naam nodig hebben om te functioneren, waaronder inputvelden, dropdowns, knoppen, tabs, checkboxes, radiobuttons, formulieren, tabellen, kolommen en vergelijkbare interactieve of databindende componenten. Puur decoratieve elementen hoeven geen aparte technische naam te krijgen.
3.6 Schermtrace naar SRS en acceptatiecriteria
De onderstaande tabel legt per schermrequirement de koppeling naar het centrale schermrequirements-trace-register, SRS-requirements en acceptatiecriteria vast. De normatieve requirementtekst staat in de SRS; dit schermdocument beschrijft alleen de lokale schermcontext.
Gebruik REQ-SCH-* alleen als lokaal schermanker. Nieuwe normatieve eisen worden niet in schermdocumentatie vastgesteld, maar horen in de SRS of, voor technische implementatie, in het Technisch Ontwerp. Business rules, validaties en proceslogica worden niet dubbel integraal overgenomen wanneer Functioneel Ontwerp of Software Requirements Specification al de bron van waarheid zijn; verwijs in dat geval naar de betreffende bron.
Aanbevolen basisvelden voor scherm meta data:
- Scherm-ID
- Schermnaam
- Doelgroep / onderdeel
- Bronbestand
- Mockupversie
- Processtap / context
- Documentatiestatus
- Opmerkingen
- Route / URL-patroon
- Autorisatie / vereiste rol-context
- Primair domeinobject / hoofdentiteit
- Gerelateerde schermen / navigatie
Aanbevolen basisvelden voor UI-elementen en velddefinities:
Aanvullend wordt aanbevolen om voor relevante interactieve elementen een technische naam vast te leggen in Engelstalige CamelCase-vorm met een hoofdletter aan het begin, bijvoorbeeld StatusDropdown of SaveButton.
| Element-ID | Type | GUI-verwijzing | Omschrijving | Zichtbaar label | Opmerking | Technische naam |
|---|---|---|---|---|---|---|
Aanbevolen basisvelden voor waardelagen:
| Element-ID | GUI-verwijzing | Zichtbaar label | Technische naam | Databron | Waardebron | Datatype | Bewerkbaar | Validatie / regel |
|---|---|---|---|---|---|---|---|---|
Aanbevolen basisvelden voor schermtrace naar SRS en acceptatiecriteria:
De schermdocumentatie bevat geen normatieve requirementtekst. Gebruik REQ-SCH-* alleen als schermanker en verwijs naar centrale SRS-requirements en acceptatiecriteria.
| Schermrequirement | Dekt | Schermcontext |
|---|---|---|
REQ-SCH-... | SRS-..., AC-... | Korte schermcontext waarin de centrale eis wordt toegepast, getoond of getoetst. |