Topic 6 · Class activity 2 · Week 15 · Friday

Cold-Start README Test and Demo Dry Run

Somebody who has never seen your compiler tries to build it from your README. Then you explain it out loud and they interrupt.

Format groups of threeTime 50 minBring a draft README and a machine you can clone onto

The point

Two things get tested here, and both are tested by somebody who is not you: can a stranger build your compiler, and can you explain it out loud under questioning.

Part 1 — the cold-start README test (25 min)

  1. Swap repositories. Clone a group member's compiler into a fresh directory. Do not ask them anything, and do not let them watch.
  2. Follow their README literally. Every place you had to guess, improvise or ask is a bug in the README. Write each one down.
  3. Score it. Could you build it? Run it on your own input? Find out what the language accepts without opening parser.y? Did the limitations section tell you something you then confirmed?
  4. Hand back your list, and fix your own README before you leave.

Part 2 — the demo dry run (25 min)

Eight minutes each, to the other two. The audience's only job is to interrupt with why, and to ask at least one question the presenter cannot answer.

  1. Show it run before explaining anything.
  2. Follow one construct through all six phases. Have the files open already — do not spend demo time navigating.
  3. Name a decision and defend it. Short-circuit or eager, table or chain, desugar or lower directly. The audience should push back once.
  4. Present one number, with its baseline and method.
  5. Give two limitations with reasons.
  6. Audience feedback: one thing that was convincing, one that was not, and the question they would have asked with more time.
The most common demo mistake

Explaining for six minutes and demonstrating for one. Lead with the working program: everything afterward lands differently once the viewer has seen the thing actually work. The second most common mistake is reading code aloud — the viewer can read, and what they cannot get from the repository is why it is shaped that way.

Deliverable

The list of README problems you found in someone else's, the list they found in yours, and your fixed README. Plus your written notes from the demo feedback — those go straight into your recorded video.