2026-04-27 20:36:08lisa:
Context Diagram: add OtterWiki blocks for visual rhythm
- TIP after intro: explicit C2-2 stake (hand-drawing under timed conditions)
- INFO callout: 'diagnostic test' framing of the Why section's punchline
- WARNING block wraps the 'not allowed' rules with a marker-strict reminder
- IMPORTANT alert highlights the 'restraint is the point' takeaway after the worked example
- SUCCESS quality-check after the How-to-draw procedure (5 ticks before moving on)
- DANGER block wraps Most common mistakes for visual urgency
sd/C02/Context Diagram.md ..
@@ 6,6 6,9 @@
A context diagram is the **highest-level** view of your software system: one shape for the whole system, the external entities it talks to, and the named data flows between them. Nothing inside, nothing extra. It is the diagram that defines the **scope** of what you are building — and it is the foundation every later diagram (Level-1 DFD, use case) must stay consistent with.
+
> [!TIP]
+
> Your **C2-2 validation** asks you to **hand-draw** a context diagram, a Level-1 DFD, and a use case diagram under timed conditions. The context diagram is the simplest of the three — but the entities and flows you choose here lock in what the other two must show. Get this one right and the rest become much easier.
+
---
## Watch first (≈5 min total)
@@ 31,7 34,9 @@
- **Visualises data exchanges** — every input and output, named
- **Anchors later diagrams** — your Level-1 DFD must show the same entities and flows
-
If you can't draw a clean context diagram for your project, you don't yet know what you're building.
+
::: info
+
**The diagnostic test.** If you can't draw a clean context diagram for your project, you don't yet know what you're building. Coming back to it after a week of design work usually reveals an entity you missed — that's a feature of the diagram, not a failure.
+
:::
---
@@ 43,12 48,16 @@
| **External entities** | Rectangles outside the circle | People, organisations, or other systems that interact with yours. Examples: *Customer*, *Administrator*, *Payment Gateway*, *Email Server*. |
| **Data flows** | Labelled arrows | Every arrow names the **specific data** crossing the boundary. Direction shows whether data goes in or out. |
-
What's **not** allowed on a context diagram:
+
::: warning
+
**What's *not* allowed on a context diagram**
- More than one process circle (that's a DFD — see [Context Diagram vs Data Flow Diagram](Context%20Diagram%20vs%20Data%20Flow%20Diagram.md))
- Data stores (no parallel-line rectangles at this level)
- Arrows between two entities (every flow must touch the system circle)
+
These rules are *strict*, not stylistic. Breaking any of them turns your context diagram into a different (and incorrect) artefact in the marker's eyes.
+
:::
+
---
## Worked example: Sales Order System
@@ 82,7 91,8 @@
- **Customers → System**: Customer details, Order and Order-line
- **System → Customers**: Order Invoices
-
Notice what is **not** shown: how the system stores employees, how it validates an order, how it produces an invoice. Those are internal — they belong on the Level-1 DFD, not here.
+
> [!IMPORTANT]
+
> Notice what is **not** shown: how the system stores employees, how it validates an order, how it produces an invoice. Those are internal — they belong on the Level-1 DFD, not here. *Restraint is the diagram's whole point.*
---
@@ 93,15 103,29 @@
3. **Name every data flow.** Walk through each entity in turn: what specific data does it send in? What does the system send back? Use specific labels (*"payment details"*, not *"information"*).
4. **Check completeness.** Every entity should have at least one arrow connecting it to the system. Every arrow should be labelled. No entity should connect directly to another entity.
+
::: success
+
**Quality check before you move on**
+
+
- Exactly **one** circle? ✓
+
- Every entity is a rectangle outside the circle? ✓
+
- Every arrow has a **specific** label (not *"data"* or *"info"*)? ✓
+
- No entity-to-entity arrows? ✓
+
- No data stores, no internal processes? ✓
+
+
Five ticks → ready for your Level-1 DFD.
+
:::
+
---
-
## Most common mistakes
+
::: danger
+
**Most common mistakes**
-
1. **Drift toward a DFD** — adding a second circle (e.g. "Verify User") inside the system. If there's more than one circle, it's no longer a context diagram.
+
1. **Drift toward a DFD** — adding a second circle (e.g. *"Verify User"*) inside the system. If there's more than one circle, it's no longer a context diagram.
2. **Unlabelled arrows** — *"data"* or *"info"* is not a label. Name the actual data.
3. **Entity-to-entity arrows** — every flow must touch the system. If two entities exchange data without your system involved, that exchange isn't on this diagram.
4. **Missing entities** — forgetting downstream systems (email server, payment gateway, reporting tool) that your system sends data to.
5. **Inventing detail** — showing data stores or internal logic. Save those for the Level-1 DFD.
