2026-04-28 17:03:38lisa:
What Is an Entity: add Gherkin scenarios as optional entity-discovery tool
Adds a 'Going further' subsection with the LitheSpeed Gherkin video
(~1 min), a Given/When/Then ATM example, and a worked breakdown
showing which entities the scenario surfaces. Framed explicitly as
not curriculum-required but powerful — the Given preconditions and
Then effects force students to name external systems they'd miss
from the user story alone.
sd/C02/What Is an Entity.md ..
@@ 71,6 71,43 @@
Work through every user story before finalising your context diagram.
+
### Going further: Gherkin scenarios *(optional but excellent)*
+
+
::: info
+
**Not required by the VCAA curriculum** — but a powerful tool for surfacing entities you'd otherwise miss. Worth knowing if you want top-band detail.
+
:::
+
+
A Gherkin scenario expands a user story into concrete **Given / When / Then** steps. Every noun in those steps is a candidate entity.
*LitheSpeed — What Is Gherkin? (~1 min). The bare-bones intro; no need to learn the BDD tooling around it.*
+
+
**Example.** A user story like *"As an account holder I want to withdraw cash so that I have money for the day"* expands to:
+
+
```gherkin
+
Feature: Account Holder withdraws cash
+
+
Scenario: Account has sufficient funds
+
Given the account balance is $100
+
And the card is valid
+
And the machine contains enough money
+
When the Account Holder requests $20
+
Then the ATM should dispense $20
+
And the account balance should be $80
+
And the card should be returned
+
```
+
+
**Entities this scenario surfaces** (each underlined noun is an external system the ATM software talks to):
+
+
- **Account Holder** — the human user (you'd already have this).
+
- **Card / Authentication system** — *"the card is valid"* implies an external check (bank network or token validator).
+
- **Bank account database** — *"balance is $100 → $80"* means your software reads and writes to an external account store.
+
- **Cash dispenser hardware** — *"dispense $20"* is a physical subsystem outside your software.
+
- **Card reader hardware** — *"card should be returned"* is another physical subsystem.
+
+
A user story alone might surface only *Account Holder*. The Gherkin expansion forces you to confront every Given precondition and every Then effect — that's where the missing entities live.
