YAML-First Demo Automation for DevRel Teams

The Demo Maintenance Problem

Every DevRel team knows this pain: you create a demo for a conference talk. It works great. Six months later, the API has changed, and the demo is broken. You have no idea what needs updating because the demo lives in some GUI tool or a collection of curl commands in a Notion doc.

Meanwhile, your engineering team updates their code in Git, runs tests in CI, and deploys with confidence. Why should demos be different?

Demos as Code

The "as code" movement has transformed infrastructure (Terraform), configuration (Ansible), and pipelines (GitHub Actions). The same principles apply to demos:

Principle	Infrastructure as Code	Demos as Code
Version control	Track infrastructure changes in Git	Track demo changes in Git
Review	PR reviews for infrastructure	PR reviews for demos
Reproducibility	Same config = same infra	Same YAML = same demo
Collaboration	Multiple engineers edit configs	Multiple DevRel edit demos
Automation	CI/CD for deployments	CI/CD for demo publishing

Why YAML?

YAML is the lingua franca of DevOps. Your team already knows it from:

• GitHub Actions workflows
• Docker Compose files
• Kubernetes manifests
• CI/CD configurations
• Ansible playbooks

Using YAML for demos means zero learning curve. A demo definition looks like this:

title: "Payments API Quick Start"
description: "Process your first payment in 3 steps"

settings:
  base_url: "https://api.example.com"

steps:
  - slide: |
      # Welcome to Payments API
      Process payments with just 3 API calls.

  - rest: POST /charges
    title: "Create a charge"
    form:
      - name: amount
        type: number
        default: 1000
      - name: currency
        default: "usd"
    save:
      chargeId: id

  - slide: |
      ## Success!
      Charge **$chargeId** created.

      [View documentation](/docs)
        

Anyone who can read a GitHub Actions workflow can read this. No proprietary formats, no vendor lock-in.

Benefits for DevRel Teams

1. Version Control Everything

Every change has an author, timestamp, and commit message. You can diff versions, revert mistakes, and understand the full history of a demo.

2. Code Review for Demos

Pull requests aren't just for code. When demos are YAML files:

• Teammates can review changes before they go live
• Suggest improvements in PR comments
• Catch errors before they embarrass you on stage
• Maintain quality standards across the team

3. Stay in Sync with API Changes

When your API adds a new required field, you'll know. Put demos in the same repo as your API, and:

• CI can validate demos against the current API spec
• Breaking changes trigger demo updates
• Demos are always tested against the latest API

# .github/workflows/validate-demos.yml
name: Validate Demos
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g demoscript
      - run: demoscript validate demos/
        

4. Reuse and Composition

YAML supports anchors and references. Define common steps once, reuse everywhere:

# _common.yaml
auth_step: &auth
  - rest: POST /auth/token
    title: "Authenticate"
    form:
      - name: api_key
        default: "demo_key"
    save:
      token: access_token

# payments-demo.yaml
steps:
  - *auth  # Reuse auth step
  - rest: POST /charges
    headers:
      Authorization: "Bearer $token"
        

5. Multiple Output Formats

From a single YAML source, generate:

• Interactive web demo — For documentation and landing pages
• Static HTML — For offline viewing and distribution
• Video/GIF — For social media and presentations
• Markdown — For blog posts and tutorials

Write once, publish everywhere.

Workflow for DevRel Teams

Here's how a YAML-first demo workflow looks in practice:

Creating a New Demo

1. Create a branch: git checkout -b demo/new-feature
2. Write the YAML demo file
3. Test locally: demoscript serve demos/new-feature.yaml
4. Open a PR for review
5. Merge to main
6. CI automatically publishes

Updating for API Changes

1. Engineering merges API change to main
2. CI runs demo validation, catches breaking change
3. DevRel gets notified via failing check
4. Update demo YAML to match new API
5. PR, review, merge
6. Demo stays in sync

Preparing for a Conference

1. Branch from main: git checkout -b conf/api-world-2026
2. Customize demo for specific audience
3. Test with live API in staging
4. Record backup responses for offline mode
5. Present with confidence
6. After conf, decide: merge customizations or discard

Collaboration Patterns

DevRel teams are distributed. YAML demos enable collaboration patterns that GUI tools can't match:

Async Collaboration

Team members in different time zones can:

• Review demos via GitHub/GitLab
• Suggest changes with line-level comments
• Approve and merge without meetings

Templates and Standards

Create team-wide standards:

• Demo templates for common patterns
• Shared components (auth flows, error handling)
• Linting rules for consistency
• Brand-compliant themes

Community Contributions

If your demos are open source:

• Community can submit fixes via PR
• External contributors can add demos
• Demos improve alongside your API

Getting Started

Ready to try YAML-first demos? Here's a quick start:

# Install
npm install -g demoscript

# Create your first demo
mkdir demos && cd demos

# Create demo.yaml with your steps
cat > demo.yaml << EOF
title: "My API Demo"
settings:
  base_url: "https://api.example.com"

steps:
  - slide: "# Welcome to my API"
  - rest: GET /health
    title: "Check API status"
EOF

# Run locally
demoscript serve .

# Open http://localhost:3000
        

Key Takeaways

• Demos suffer from the same problems as pre-DevOps infrastructure
• YAML brings version control, review, and automation to demos
• DevRel teams already know YAML from DevOps tools
• Single source, multiple outputs (web, video, docs)
• Collaboration improves with PRs and async review
• API changes can trigger demo updates automatically

The future of DevRel tooling is code-first. YAML demos are a natural fit for technical teams who already embrace "as code" practices.