Demo Script for a Portfolio Project. A Build Next Stack field guide for learners shipping small projects.
Demo goal: one problem solved in ninety seconds
Portfolio demos fail when builders improvise feature tours. Quinn writes a script that shows one user problem solved start-to-finish in under ninety seconds—recruiter attention span, friend at coffee patience, your own clarity test.
Script opens with problem sentence spoken aloud: I forget which CLI flags I used last week. Then screen shows the fix—not architecture slides first. Architecture comes in README; demo sells outcome.
Beat sheet before pixels
Quinn’s beat sheet template:
- Hook — problem in one sentence (5 sec)
- Setup — show empty or broken state (10 sec)
- Action — two clicks or one command max (40 sec)
- Result — visible payoff (20 sec)
- Teaser — one line on stack or learning (15 sec)
Time each beat while rehearsing. Over ninety seconds means cut beats, not talk faster.
Seed data and happy path only
Demo environment is not production. Quinn ships scripts/seed-demo.sh that creates predictable users, sample files, or API responses. Reset before every recording—no live random data that embarrasses.
Hide destructive buttons during demo builds via env DEMO_MODE=1 if needed. Demo mode can simplify nav or show helper tooltips—label them in script so you do not forget toggles.
Script doc alongside README
Store docs/demo-script.md with:
- Spoken lines in quotes
- Click-by-click actions in monospace
- Fallback if Wi-Fi dies—offline recording clip or screenshots
- Known bugs to avoid on camera
Future you preparing a job application reuses script without reconstructing from memory. Update script when UI changes—same commit as UI or demo lies.
Recording setup that survives solo constraints
Quinn records 1080p screen plus mic—OBS or built-in macOS recorder. Close notifications; enable Do Not Disturb. Browser zoom 125% so text readable on phones. One take policy for practice; publish take three or four when audible ums drop.
Keep raw recordings one week; export trimmed MP4 or GIF under ten megabytes for README embed or LinkedIn. Host on same domain or reputable video host—broken embeds worse than no video.
Live demo vs async video
Live interviews need shorter script—sixty seconds plus two minute deep dive if asked. Async portfolio allows polished ninety-second cut plus optional long walkthrough unlisted.
Prepare answer for what would you add next—one honest limitation from README non-goals. Shows judgment, not feature wishlist fantasy.
Rehearsal checklist before sharing link
Before sending demo URL:
- Reset seed data
- Incognito window—no extension noise
- Script timed under ninety seconds
- Captions or transcript pasted below video for accessibility
- Link works on phone once
First impression is often mobile Slack preview—not your laptop glory.
When the project is CLI-only
No GUI still demos. Quinn records terminal with asciinema or typed script in VS Code terminal with large font. Show before output mess, run one command, show after clean result. Voiceover explains flags chosen.
ASCII demo beats slides about CLI. Keep command count low; link to README for advanced flags.
Quinn stores demo recording settings in script footer—OBS scene, mic name, font size—so re-recording six months later matches quality without re-tuning from scratch.
Portfolio page copy that matches the demo
README hero paragraph repeats demo hook sentence—problem first, stack second. Quinn avoids leading with React version; leads with See every CLI command you ran this week in one scrollable list. Recruiter skimming text and video gets consistent story.
Call to action one link: live demo, video, or repo— not five equal buttons. Primary link matches what you can support this month.
Update hero when demo script changes; mismatched copy and video confuse more than no video.
Practice schedule before high-stakes share
Quinn rehearses three times spaced across days—not one cram hour. Spacing catches tongue twister UI labels and awkward pauses. Record practice take; watch muted once for visual stumbles only.
Ask one technical friend for feedback on clarity, not praise. Single question: What problem did this solve? Wrong answer means script hook failed, not demo polish.
High-stakes share includes job application, conference lightning talk, or Product Hunt—same ninety-second core, optional extended cut linked second.
Failure modes Quinn cut from early demos
Feature tour: clicking every settings panel—cut to one path.
Live coding: typos on camera—record typed commands or use seed script.
Apology loop: sorry UI is rough—state one limitation once, move on.
No mic check: viewer leaves; test audio first ten seconds every take.
Cut list lives in demo-script.md as reminders before recording marathon weekends.
Quinn archives best take filename in README—demo-v3-2026-06.mp4—and deletes takes one and two after v3 ships. Disk clutter hides which file is canonical when updating portfolio six months later.
Accessibility and transcript habit
Every published demo gets paste transcript below video—auto-caption export cleaned once. Recruiters in open offices and deaf colleagues appreciate it; SEO picks up problem keywords you spoke aloud.
Transcript editing takes ten minutes for ninety seconds audio—cheaper than re-recording because captions were wrong.
Describe on-screen action in spoken line once—I click Export CSV here—so audio-only listeners follow.
Quinn links demo video from repo README top—above install instructions—because visitors who need convincing watch before cloning. Order matches funnel: outcome first, setup second.
Versioning demo media with the app
Filename includes app semver when demo shows version-specific UI—demo-v1.4-export.mp4. Outdated demo worse than none when button moved. Re-record trigger: any user-visible flow change in release notes.
Keep script and video in same release PR when possible. Reviewers—still you—watch once before merge.
Old demos move to docs/archive/demos/ unlisted rather than deleted—useful for comparing UX iteration in portfolio writeups.
Quinn rehearse-aloud rule: if hook sentence exceeds twelve words, shorten. Long hooks lose viewers before setup screen appears.
Write the beat sheet before recording
Open your strongest side project and draft docs/demo-script.md with hook, setup, action, result—timed aloud once. Cut until under ninety seconds.
Seed predictable data and reset before every take. Demos fail on random state, not missing features.
A small polished demo communicates shipping better than a large unfinished app. Script first, pixels second.