Ship Better Code, Faster

Appearance

Workshop 4: Slide Content ​

Deck title: Developer Experience Engineering & Tooling Duration: 60 minutes · ~22 slides

Slide 1: Title [lavender title slide] ​

Title: Remove the friction. Eyebrow: Session 4 of 8 · Developer Experience Engineering

Slide 2: Recap [white, headline + body] ​

Title: CI made the pipeline fast. DevEx makes the whole job faster. Subtitle: Where we are in the arc Body: A fast pipeline is only one part of the developer's day. The hour they spend setting up their environment, the README that lies to them, the script that breaks on a typo: those cost just as much. Today we fix the human-shaped parts of the codebase.

Slide 3: Agenda [dark blue, agenda layout] ​

Title: Agenda Bullets (5):

  • 10 min: DevEx principles and the DORA / SPACE frameworks
  • 10 min: Audit the repo from a new developer's perspective
  • 5 min: Audit again from a platform team's perspective
  • 15 min: Implement setup scripts and improve documentation
  • 10 min: Onboarding before/after, and the DevEx career path

Slide 4: Section divider [dark blue] ​

Big text: What developer / experience means.

Slide 5: Defining DevEx [white, headline + body] ​

Title: Developer experience is a product Subtitle: The shift in thinking Body: The product is the engineering organization itself. The users are your teammates. The "checkout funnel" is the time from "I got the laptop" to "my first PR merged." DevEx engineers measure that funnel and improve it, the same way a growth engineer measures a customer signup funnel. Once you see it that way, you can't unsee it.

Slide 6: DORA + SPACE [white, 2-col] ​

Title: Two frameworks worth knowing Left subhead: DORA Left body: Four metrics: deployment frequency, lead time for changes, change failure rate, mean time to recovery. These came out of the State of DevOps research. We use them in Session 6. They tell you "is the team shipping well?" Right subhead: SPACE Right body: Five dimensions: satisfaction, performance, activity, communication, efficiency. Broader than DORA. SPACE is more about "is the team happy and effective?", the soft side. Worth reading; we won't drill into it today.

Slide 7: What real teams measure [dark, headline + body] ​

Title: What real DevEx teams measure Subtitle: Concrete examples Body: Time to first PR for a new hire. % of engineers who can build the codebase in under 5 minutes. % of pull requests that touch the build system in a given month. Developer satisfaction surveys, quarterly. None of these are hypothetical: Stripe, Spotify, and Shopify all publish numbers like these.

Slide 8: Section divider [dark blue] ​

Big text: Audit the / repo.

Slide 9: The new-developer test [white, headline + body] ​

Title: Pretend you've never seen this codebase Subtitle: Workshop, 10 minutes Body: We open OrbitTasks together like it's a brand-new repo. Read the README top to bottom. Follow it literally: clone, install, run. Together we list every place we got stuck, surprised, or had to guess. Don't fix anything yet; just collect data. Record it in your logbook as we go.

Slide 10: Patterns you'll find [white, title + body + bullets] ​

Title: Patterns to look for Body: Most OAF Fellows find a similar set of issues. Use these as prompts when you're auditing. Bullets (4):

  • The README promises a simple flow but skips required setup steps (env vars, migrations, seeds).
  • A script exits with an error because of a small bug or platform-specific assumption.
  • Documentation references tools that aren't actually used anymore.
  • Scripts in package.json are named inconsistently: dev here, start there, serve elsewhere.

Slide 11: The platform team angle [dark, headline + body] ​

Title: Now switch hats: you're on the platform team Subtitle: Workshop, 5 minutes Body: Same repo, different lens, done together. What about this codebase makes it hard for your team to maintain it across many similar projects? What conventions are missing? What would you wish every repo in the org had? Record what we find in your logbook as we go.

Slide 12: Section divider [dark blue] ​

Big text: Now build / the fixes.

Slide 13: Setup scripts [white, headline + body] ​

Title: The one-command setup script Subtitle: The single biggest DevEx win Body: If a new developer can run make setup (or npm run setup) and have a fully working environment afterward (including env vars, the seeded database, and both dev servers), they're in the codebase 5 minutes after cloning instead of 5 hours. (Today there is no root start/dev script: you run npm run dev --workspace=apps/api and npm run dev --workspace=apps/web, after npm run seed --workspace=apps/api. Wrapping that into one command is the deliverable.) We're going to build that script today.

Slide 14: Makefile vs npm scripts [white, 2-col] ​

Title: Makefile or npm scripts? / Either is fine. Left subhead: Makefile Left body: Old-school. Works for any project regardless of language. Great for monorepos with mixed stacks. make setup, make dev, make test, make ci. Some teams love it; some teams find tabs-vs-spaces irritating. Right subhead: npm scripts Right body: Everyone on a JS team already knows them. Limited to JavaScript-ish workflows but those workflows cover 99% of the use cases. We'll use both today: Makefile at the root, npm scripts inside each app.

Slide 15: Workshop: build the entry points [white, headline + body] ​

Title: Workshop, 15 minutes Subtitle: Make make setup actually work Body: Together we write (or fix) scripts/setup.sh and create a top-level Makefile. Targets to implement: setup, dev, test, ci, clean. Make sure setup seeds the database (npm run seed --workspace=apps/api); the local DB starts empty. Then we update the README so the documented path matches what the script does. The acceptance test: a teammate clones the repo and runs make setup. Done = you can log in with demo@orbittasks.local / Password123 and see the task board, not just "the API boots." They should be there inside 5 minutes. Follow along in your own clone.

Slide 16: Documentation [dark, title + body + bullets] ​

Title: Documentation that doesn't / lie to you. Body: Out-of-date docs are worse than no docs at all. Three rules: Bullets (4):

  • Document only what you actually do. Aspirational documentation rots fastest.
  • Keep the README to one page. Link out to deeper docs in docs/.
  • For every command in the README, verify by running it on a fresh clone.
  • Add "Last verified: 2026-05-26" at the bottom. Future you will be grateful.

Slide 17: Tools that reduce toil [dark, headline + body] ​

Title: A few small tools that pay back fast Subtitle: Pick one or two to add today Body: Pre-commit hooks (with Husky) catch formatting issues before push. Devcontainers / .env.example files speed up onboarding. concurrently and wait-on make multi-process dev servers a single command. dotenv-vault or 1Password CLI handle secrets cleanly. You don't need all of these. Pick the one that solves a real pain you saw today.

Slide 18: Section divider [dark blue] ​

Big text: Measure / the win.

Slide 19: Before/after [white, headline + body] ​

Title: Time it. Subtitle: Workshop, 10 minutes Body: Together, on a fresh clone (or make clean then a fresh make setup), we time how long it takes to go from "I just cloned" to "I have the app running locally." Compare to the time we estimated for the original flow earlier. The delta is your improvement. Record both numbers in your logbook as we go.

Slide 20: Career angle [white, title + body + bullets] ​

Title: The DevEx career path / is real and growing. Body: Five years ago DevEx wasn't a job title. Today it is, at every company over ~50 engineers. Bullets (4):

  • Titles you'll see: "Developer Experience Engineer," "Productivity Engineer," "Internal Tooling."
  • Salary bands track Platform Engineering: $140k–$220k for mid-senior in major markets.
  • The work blends software engineering, product sense, and human-factors thinking.
  • The portfolio you build here is an interview-quality artifact for this exact role.

Slide 21: Looking ahead [white, headline + body] ​

Title: Session 5: AI-assisted development and evaluation Subtitle: What changes next session Body: You'll use AI coding tools (Claude, Copilot, ChatGPT) to refactor a real module, generate unit tests for an untested service, and produce documentation. Then we critique the output. Some of it will be great; some of it will be wrong. Learning to tell the difference is the lesson.

Slide 22: Questions [dark blue, Big Stat layout] ​

Big text: Questions?