Skip to main content

Use Case Best Practices for WepNG

To complement our Gherkin Strategy for automated logic, we use Use Cases to describe human-centric interactions and workflows.

1. When to use a Case vs Gherkin​

FormatBest ForFocus
Gherkin"Invisible" Business Rules, Calculations, SQL LogicData State
Use CaseUser Interactions, UI Workflows, End-to-End ProcessesHuman Goal

2. The Format (Cockburn "Fully Dressed" Lite)​

We use a Markdown template that balances readability with technical precision.

Template​

[!TIP] You can copy the raw Use Case Template to start.

# UC-001: [Verb] [Noun] (e.g., Assign Callback)

**Actor**: [Role] (e.g., Operator, Manager)
**Goal**: [What does the user want to achieve?]
**Trigger**: [What starts this?]

## Main Success Scenario
1. Actor clicks X.
2. System validates Y.
3. System shows Z.

## Extensions (Alternatives)
2a. Validation fails:
    1. System shows error.
    2. Actor retries.

## Technical Mapping (Developer Notes)
*   **Controller**: `ToDoListMGTController`
*   **Action**: `Assign`
*   **Key Entities**: `ToDoListNG`, `Callback`

3. Writing Rules​

Rule 1: "User Intention", not "Button Clicks"​

Avoid describing every CSS class or exact pixel position.

  • ❌ Bad: User moves mouse to the top right and clicks the green button with icon 'fa-save'.
  • ✅ Good: User confirms the assignment.

Rule 2: System vs Actor​

Clearly distinguish who is doing what. Step 1 is usually the Actor; Step 2 is the System response.

  • 1. User selects a target.
  • 2. System verifies availability.

Rule 3: The "Technical Mapping" Section​

Just like our Gherkin .mapping.md, every Use Case must have a section for Developers. This bridges the gap between "Functional Spec" and "Implementation".

  • Mention the Controller/Action involved.
  • Mention the Database Entities touched.
  • Mention any Legacy Dependencies (e.g., "Relies on GlobalSession").

4. Storage Structure​

Use Cases reside in docs/specs/[Module]/[Component]/. Example: docs/specs/omgt/tasks/AssignCallback.md