ralvarezdev Demo Script Architect
Design and refine presenter-centric demo scripts that guide audiences through system capabilities in a natural, engaging narrative flow. Works for any technical or product demo.
When to use
Creating live demonstration scripts; building structured walkthroughs of systems/features; designing progressive capability reveals; turning technical specs into engaging narratives; adding visual guidance for presenters.
1. Core principles
- Narrative over features. Each section builds on previous learning; bridge narration explains the why. Story arc: observe → understand → apply → verify. Conversational, not documentation-style.
- Element documentation. Always include element purpose when referenced:
YI-100 (pump status indicator). Help the audience understand what they're looking at. - Visual guidance mapping. Map abstract references to actual visible elements. Data field
"status"→ point to the status icon/light. Never point to something the audience can't see on screen. - Query-to-explanation alignment. The explanation must accurately describe what's being queried — don't claim "context-learning" if tags are explicit. Explain the mechanism (parallelization, routing, lookup) and set up expectation for the response.
- No redundancy. Don't repeat the same query/capability in consecutive demos. Build progressive revelation: basic → complex → combined → edge cases. Stack elements only when combining for a new insight.
- Conversational tone. Use contractions ("it's", "we've"). Direct the audience ("Watch", "Notice", "Observe"). Short punchy sentences over long lists. Tell a story.
- Commentary interprets, doesn't restate. Explains significance, not mechanics; sets up the next logical question.
2. Narrative section structure
Every demo follows the same six-part shape:
Demo Setup → purpose, what to watch for
Visual Cue → "[On screen: Point to X, watch Y]"
Action/Query → explicit ask of the system
Processing → 2-3 audience-friendly sentences on what's happening
Expected Responses → multiple outcomes based on system state
Commentary → interpret results, relate to broader picture
3. Demo progression template
| # | Focus | New capability | Approach |
|---|---|---|---|
| 1 | Basics | Single element access | Explicit reference |
| 2 | Integration | Multiple related elements | Grouped query |
| 3 | Abstraction | Natural language, no explicit refs | System infers intent |
| 4 | Dynamics | Live data, change over time | Continuous monitoring |
| 5 | Accessibility | Different access methods | Voice/touch/alternative interface |
| 6 | Automation | System behavior without command | Observe automatic logic |
| 7 | Diagnostics | Troubleshooting scenario | Bundle related elements |
| 8 | Knowledge | Search/lookup capability | Find answers in resources |
| 9 | Control | Issue commands | Write operations + verification |
4. Anti-patterns
| Anti-pattern | Wrong | Right |
|---|---|---|
| Explanation/query mismatch | Query mentions YI-100, SI-100, PIT-100; explanation says "we didn't mention specific tags this time" |
"Three different data points from two systems in parallel" |
| Pointing to invisible | "[Point to field PIT-100 on screen]" when not labeled |
"[Point to the pressure gauge display]" |
| Robotic narration | "System processes query, retrieves values from database, returns formatted response." | "Watch the system grab the values and hand them back as one answer." |
| Redundant demos | Demo 1 status query → Demo 2 same status query | Demo 1 status query → Demo 2 combine status with related data |
| Weak bridge | "Now let's do a different demo." | "Now that we know the status, let's check the pressure to see what it's delivering." |
5. Review checklist
- Each demo has a Setup explaining purpose
- Actions/Queries are explicit and clear
- Processing accurately describes what's happening
- Visual cues point to visible screen elements
- Element names include purpose:
NAME (what it does) - Commentary interprets results
- Bridge narration connects each demo to the next with a why
- No redundant queries (same action shown twice for same purpose)
- Multiple expected responses cover realistic system states
- Tone is conversational throughout (no robotic jargon)
6. Output deliverables
- Structured script with the six-part narrative sections (§2).
- Visual element map — reference → visible screen element.
- Demo flow diagram showing connections and progression.
- Redundancy audit — what was removed/consolidated and why.
- Presenter notes — what to watch for, where to point, what to emphasize.