Ship Better Code, Faster

Appearance

Workshop 4: Developer Experience Audit Handout ​

We work through this together, live, in the session. Follow along in your own clone.

Record your results in your logbook as we go. The before/after timings are part of your Workshop 6 evidence, so keep your logbook: we reuse it in Workshop 6 and Workshop 8.

Part 1: New-developer audit ​

Together we treat OrbitTasks as if we've never seen it. We read the README and follow it literally, capturing every place we got stuck, surprised, or had to guess.

For each issue, note what you tried, what happened, and what was missing or wrong. Record this in your logbook as we go.

Also capture your estimated time from clone to running app (before fixes). Record this in your logbook as we go.

Part 2: Platform-team audit ​

Now we switch hats together. We're on the platform team responsible for many similar repos. What's missing from OrbitTasks that you'd want every repo in the org to have?

Record what we find in your logbook as we go.

Part 3: Fixes we implement together ​

We implement these live, in session. You don't need to do all of them; we work through the highest-impact ones together. Anything beyond the core fixes is optional polish.

  • Fix scripts/setup.sh so it runs cleanly (incl. the logss typo)
  • Document the required seed step (npm run seed --workspace=apps/api); local DB starts empty, login fails without it
  • Rewrite the top-level README to match reality
  • Add a Makefile with setup, dev, test, ci, clean targets
  • Add .env.example content for every required variable (JWT_SECRET, DATABASE_URL)
  • Standardize package.json script names across apps/api and apps/web
  • (Optional) Add a pre-commit hook (Husky) for formatting
  • (Optional) Add a .nvmrc and document the Node version
  • Update docs/architecture.md to reflect the actual stack

As you apply each fix, note which ones you shipped. Record this in your logbook as we go.

Part 4: Before/after onboarding time ​

After the fixes, we measure again, together. Time from a fresh clone (or make clean + fresh make setup) to the app running locally. Done = you can log in with demo@orbittasks.local / Password123 and see the task board, not just "the API boots."

Capture the before time, the after time, the time saved, and the steps required for each. Record this in your logbook as we go.