Writing Effective Project DescriptionsLesson 4.4

How to add a live demo GIF or screenshot to a portfolio project

screen recording tools, GIF creation, LICEcap, Kap, image optimization, WebP format, lazy loading images, alt text for accessibility, demo video embedding

Show Don't Tell: Demos That Work

A screenshot shows your UI exists. A demo GIF shows it actually works. Recruiters clicking a "Live Demo" link and finding a broken Heroku dyno is worse than no demo at all — a GIF always works.

Recording a Demo GIF

Use Kap (macOS) or ScreenToGif (Windows) to record your screen. Keep recordings under 30 seconds — one feature, one flow, one clear loop. Export at 800px wide maximum to keep file size manageable.

# Optimize GIF with ffmpeg
ffmpeg -i demo.gif \
  -vf "fps=15,scale=800:-1" \
  -loop 0 \
  demo-optimized.gif

Adding to README and Portfolio

<!-- In README -->
![Project demo GIF showing main user flow](assets/demo.gif)

<!-- In portfolio HTML — use loading=lazy -->
<img
  src="assets/demo.gif"
  alt="Dashboard showing real-time task updates"
  loading="lazy"
  width="800"
/>

Always write descriptive alt text for demos — not "demo gif" but a description of what the user sees happening. This helps screen reader users and improves SEO. Set explicit width and height attributes to prevent layout shift while the GIF loads.