Appearance
Session 4: Facilitator Notes
Duration: 60 min · Deliverable: improved setup flow, honest README, before/after onboarding comparison
Before the session
- I've cloned a fresh copy of OrbitTasks and timed my own onboarding. I know the pain points first-hand.
- I have a "good" Makefile reference ready (I don't share it unless they're stuck).
- I've made sure students know they can
make clean(orrm -rf node_modules) to test onboarding from scratch.
Time budget
| Block | Mins | Slides |
|---|---|---|
| 1. DevEx principles + frameworks | 10 | 1–7 |
| 2. New-developer audit | 10 | 8–10 |
| 3. Platform-team audit | 5 | 11–12 |
| 4. Implement fixes | 15 | 13–16 |
| 5. Before/after + career | 10 | 17–22 |
Block-by-block
Block 1. The mindset shift on slide 5 is the whole session: "DevEx is a product." Don't skip it. The DORA/SPACE frameworks (slide 6) are quick reference; don't lecture.
Block 2 (audit). We re-read the README together and follow it literally, students following along in their own clones. This is uncomfortable for some; they want to fix as they go. Tell them: collect data first, fix second. We fill the W4 logbook section together as we go (Part 1).
Block 3. The platform-team lens (slide 11) is what makes the session distinct from "let's improve some docs." Push them: what would you wish every repo in the org had? Common answers: pinned Node version, a Makefile, a .env.example, a one-paragraph "what is this" at the top of the README.
Block 4 (workshop). The deliverable, done live together. We work through the highest-impact fixes from the audit and implement them on screen while students follow along in their own clones. Most of the time goes to fixing the setup script and writing a Makefile. Going further (devcontainer, Husky) is optional polish, never required, and only if there's time. The README must end up truthful, even if minimal. We record the fixes we ship in the W4 logbook section together as we go.
Block 5 (before/after). We time it again on a fresh clone together. Most students see onboarding drop from ~10 min to ~2 min. We record the before/after numbers in the W4 logbook section together now. Career angle: real DevEx roles, real salary bands.
Anticipated questions
"Do I have to use a Makefile?"
No. Use npm scripts at the root if you prefer. The point is one command for setup.
"My setup script works locally but not on a fresh clone, why?"
Probably an OS assumption (mkdir on macOS vs Linux, etc.) or a missing dependency.
"How honest should the README be? Should I document the limitations?"
Yes. "Known issue: X fails on Windows" is better than silence. Future-you will thank present-you.
If I run short
- Compress block 1 to 5 min: skip the framework names, just the mindset.
- Cut slide 17 (tools that reduce toil); they can read it themselves.
- Never cut block 4. The fixes are the deliverable, and we do them live.
Post-session
In chat: "We brought onboarding from 'broken' to 'one command' together today, and it's all in your logbook. Keep your logbook: we reuse it in Workshop 6 and Workshop 8. Optional, if you want to go further on your own: clone from scratch and confirm make setup Just Works, or add one of the polish items we didn't get to (devcontainer, Husky)."