Initial commit: Complete TDD workshop materials
- Workshop documentation (WORKSHOP_PLAN, FACILITATOR_GUIDE, etc.) - FizzBuzz kata with demo script (git history to be recreated) - Password Validator kata with demo script and solution - Shopping Cart kata with demo script and solution - Setup guide and TDD reference card for participants
This commit is contained in:
commit
c3355063f2
26 changed files with 4725 additions and 0 deletions
199
docs/plans/2026-03-10-workshop-improvements-design.md
Normal file
199
docs/plans/2026-03-10-workshop-improvements-design.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
# TDD Workshop Improvements - Design Document
|
||||
|
||||
**Date:** 2026-03-10
|
||||
**Author:** Workshop Facilitator
|
||||
**Status:** Approved
|
||||
|
||||
## Overview
|
||||
|
||||
This document outlines the design for enhancing the TDD workshop materials to create a comprehensive, ready-to-deliver 2-hour hands-on session for developers familiar with TDD concepts but lacking practical experience.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Provide a complete live-demo kata (FizzBuzz) with step-by-step progression
|
||||
2. Enhance facilitator guidance with detailed scripts and timing
|
||||
3. Create participant reference materials (TDD cheat sheet)
|
||||
4. Add setup and troubleshooting documentation
|
||||
5. Improve solution files with test-to-code traceability
|
||||
|
||||
## Target Audience
|
||||
|
||||
- **Participants:** Developers who know what TDD is but haven't practiced it regularly
|
||||
- **Facilitators:** Workshop leaders who need clear guidance and scripts
|
||||
- **Format:** 2-hour in-person workshop
|
||||
- **Language:** Dart
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Approach: Incremental Enhancement
|
||||
|
||||
We'll build improvements in three phases:
|
||||
|
||||
1. **Phase 1:** Live demo foundation (FizzBuzz kata)
|
||||
2. **Phase 2:** Documentation (guides, reference card, setup)
|
||||
3. **Phase 3:** Polish (enhanced solutions, root README)
|
||||
|
||||
This allows for testing each component and ensures core materials are ready first.
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
tdd-workshop/
|
||||
├── README.md # NEW: Workshop overview
|
||||
├── FACILITATOR_GUIDE.md # ENHANCED: Add detailed scripts
|
||||
├── WORKSHOP_PLAN.md # NEW: Complete schedule & checklists
|
||||
├── TDD_REFERENCE_CARD.md # NEW: One-page participant handout
|
||||
├── SETUP_GUIDE.md # NEW: Installation & troubleshooting
|
||||
├── docs/
|
||||
│ └── plans/ # Design documents
|
||||
├── fizzbuzz/ # NEW: Live demo kata
|
||||
│ ├── README.md
|
||||
│ ├── DEMO_SCRIPT.md # Facilitator walkthrough
|
||||
│ ├── pubspec.yaml
|
||||
│ ├── lib/
|
||||
│ │ └── fizzbuzz.dart
|
||||
│ └── test/
|
||||
│ └── fizzbuzz_test.dart
|
||||
├── password_validator/
|
||||
│ └── lib/
|
||||
│ └── password_validator_solution.dart # ENHANCED: Add test references
|
||||
└── shopping_cart/
|
||||
└── lib/
|
||||
└── shopping_cart_solution.dart # ENHANCED: Add test references
|
||||
```
|
||||
|
||||
## Component Designs
|
||||
|
||||
### 1. FizzBuzz Demo Kata
|
||||
|
||||
**Purpose:** Provide a ready-to-demonstrate kata showing RED-GREEN-REFACTOR in real-time.
|
||||
|
||||
**Git Strategy:** Linear commit history showing each TDD cycle:
|
||||
- Commits alternate between RED (failing test) and GREEN (minimal implementation)
|
||||
- Each commit message clearly labeled: "RED: ...", "GREEN: ...", "REFACTOR: ..."
|
||||
- Facilitator can `git checkout` each commit to show progression
|
||||
|
||||
**Key Commits:**
|
||||
1. Initial setup
|
||||
2. RED: Test for 1 → "1"
|
||||
3. GREEN: Return "1" (hardcoded)
|
||||
4. RED: Test for 2 → "2"
|
||||
5. GREEN: Return n.toString()
|
||||
6. RED: Test for 3 → "Fizz"
|
||||
7. GREEN: Check divisibility by 3
|
||||
8. RED: Test for 5 → "Buzz"
|
||||
9. GREEN: Add divisibility by 5
|
||||
10. RED: Test for 15 → "FizzBuzz"
|
||||
11. GREEN: Check both (order matters!)
|
||||
12. REFACTOR: Optional cleanup
|
||||
|
||||
**DEMO_SCRIPT.md Contents:**
|
||||
- Minute-by-minute timing guide (0-5, 5-10, 10-15)
|
||||
- Talking points for each step
|
||||
- Common mistakes to demonstrate intentionally
|
||||
- Key insights participants should notice
|
||||
|
||||
### 2. Enhanced Documentation
|
||||
|
||||
#### TDD_REFERENCE_CARD.md
|
||||
One-page handout covering:
|
||||
- RED-GREEN-REFACTOR cycle diagram
|
||||
- When to refactor (code smells)
|
||||
- Common test patterns (Arrange-Act-Assert)
|
||||
- Dart test assertions quick reference
|
||||
- Tips for staying disciplined
|
||||
- Link to tdd-katas for more practice
|
||||
|
||||
#### SETUP_GUIDE.md
|
||||
Pre-workshop setup with:
|
||||
- Dart SDK prerequisites
|
||||
- Installation steps
|
||||
- Verification procedures
|
||||
- Troubleshooting common issues (pub get fails, PATH issues, etc.)
|
||||
- IDE setup recommendations
|
||||
|
||||
#### WORKSHOP_PLAN.md
|
||||
Complete facilitator reference with:
|
||||
- Pre-workshop checklist (1 week, 1 day, morning of)
|
||||
- Minute-by-minute schedule (8 segments, 120 minutes)
|
||||
- Materials checklist (digital & physical)
|
||||
- Facilitation tips (energy management, handling questions)
|
||||
- Success metrics
|
||||
|
||||
### 3. Enhanced FACILITATOR_GUIDE.md
|
||||
|
||||
**Additions:**
|
||||
- Full scripts for each segment (not just bullet points)
|
||||
- Detailed live demo section with FizzBuzz walkthrough
|
||||
- Expanded intervention table with more scenarios
|
||||
- Transition scripts between segments
|
||||
- Backup plans for running ahead/behind
|
||||
|
||||
**Structure:**
|
||||
- Each segment has "What to say", "What to do", "What success looks like"
|
||||
- Timing checkpoints throughout
|
||||
- Ready-to-use phrases for common situations
|
||||
|
||||
### 4. Enhanced Solution Files
|
||||
|
||||
**Strategy:** Add inline comments linking code to tests and explaining design evolution.
|
||||
|
||||
**Comment Types:**
|
||||
- **Test reference:** `// STEP 2: From test "rejects password with no uppercase"`
|
||||
- **Design decision:** `// Map chosen over List for O(1) lookup by name`
|
||||
- **Refactoring note:** `// Originally 5 if-blocks → extracted to rule functions`
|
||||
- **Pattern highlight:** `// This is the Open-Closed Principle in action`
|
||||
|
||||
**Benefits:**
|
||||
- Solutions become teaching tools
|
||||
- Participants see why code looks this way
|
||||
- Design patterns are explicitly named
|
||||
|
||||
### 5. Root README.md
|
||||
|
||||
**Purpose:** Orient anyone opening the repository.
|
||||
|
||||
**Sections:**
|
||||
- Workshop overview (what, why, who)
|
||||
- For facilitators (where to start)
|
||||
- For participants (how to choose a kata)
|
||||
- Repository structure explained
|
||||
- Quick start instructions
|
||||
- Links to additional resources
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: FizzBuzz Kata (30-45 minutes)
|
||||
1. Create fizzbuzz/ directory structure
|
||||
2. Set up pubspec.yaml
|
||||
3. Build kata with git commits (12 commits total)
|
||||
4. Write DEMO_SCRIPT.md
|
||||
5. Write fizzbuzz/README.md
|
||||
|
||||
### Phase 2: Documentation (45-60 minutes)
|
||||
1. Create TDD_REFERENCE_CARD.md
|
||||
2. Create SETUP_GUIDE.md
|
||||
3. Create WORKSHOP_PLAN.md (incorporate detailed schedule)
|
||||
4. Enhance FACILITATOR_GUIDE.md with scripts
|
||||
|
||||
### Phase 3: Polish (30-45 minutes)
|
||||
1. Enhance password_validator_solution.dart with comments
|
||||
2. Enhance shopping_cart_solution.dart with comments
|
||||
3. Create root README.md
|
||||
4. Review all materials for consistency
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Facilitator can run the entire 2-hour workshop using only these materials
|
||||
- [ ] Live demo kata is ready to present without preparation
|
||||
- [ ] Participants have clear setup instructions and reference materials
|
||||
- [ ] Solution files explain design decisions, not just implementation
|
||||
- [ ] All documentation uses consistent tone and terminology
|
||||
|
||||
## Open Questions
|
||||
|
||||
None - design is approved and ready for implementation.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Proceed with implementation using the three-phase approach outlined above.
|
||||
Loading…
Add table
Add a link
Reference in a new issue