Screenshots, GIFs, and video in release notes: when visuals earn their place

A screenshot of the new thing answers the reader’s only question — “what’s different for me?” — faster than any sentence you will ever write. It is the highest-bandwidth line in your changelog. It is also the heaviest asset on the page, the most distracting element in the column, the least accessible content you can publish, and the only part of an entry that most of your distribution channels will silently drop. Both facts are true at once, which is why “should release notes have screenshots?” has no one-word answer.

The rule that resolves it is the same one from the page-design guide: media follows the change. If the change is visible, show it. If it isn’t — a fix, a speedup, an API addition — a decorative image doesn’t make the entry friendlier; it makes the page slower and pushes the next real change below the fold. Everything else in this guide is working out what “show it” should mean.

The text carries the fact; the image demonstrates it

Before choosing a medium, fix the division of labor. The sentence states what changed; the picture proves and locates it. Never the reverse — the moment the only statement of a change lives inside pixels, you have hidden it from:

  • Screen reader users, who get whatever your alt text says — usually nothing (the accessibility guide covers this in depth);
  • Search engines, which index your symptom-named titles and body text, not your pixels — an image-only entry is invisible to the queries it should answer;
  • Feed readers and email clients, many of which proxy, delay, or block images outright;
  • Chat mirrors — a Discord or Slack notification is a title and a link, maybe one unfurl;
  • Plain-text exports and anyone reading your changelog as markdown.

The working test: read the entry with images turned off. If it still tells the reader what changed and what to do, the visuals are a bonus layer. If it collapses into “check out the new look! [broken image]”, the entry was a caption, not an announcement.

Pick the lightest medium that shows the change

Media has a cost ladder — production cost, file weight, and reader attention all climb together. Start at the bottom and only move up when the change genuinely can’t be shown one rung cheaper:

  • Cropped screenshot. The default for anything visible. One static image, tightly cropped to the changed region, answers “what does it look like and where do I find it?” at a few dozen kilobytes.
  • Annotated screenshot. An arrow or a box on that crop. This out-communicates a GIF more often than you’d think, because the reader controls the time: they can stare at the arrow for as long as they need, instead of waiting for a loop to come around again.
  • Before / after pair. When the change is a change to something familiar — a redesign, a relayout, a component update — two crops with the same data, same zoom, and same theme beat any amount of prose. Same data and same zoom is an honesty requirement, not a style tip: a before/after where the “after” got nicer demo content is screenshot spin.
  • Short silent loop. Only when motion is the feature — drag-and-drop, a live-updating view, a gesture. Five to ten seconds, no sound, and ideally not a GIF at all: a muted looping video file is roughly an order of magnitude smaller, can be paused, and can be told to respect the reader’s reduced-motion preference. A GIF can do none of that.
  • Demo video. Launch-tier features with a workflow to walk through, per the launch-sizing guide. A produced video belongs on the blog post or landing page; the changelog entry links to it with a thumbnail. Embedding a player in the timeline makes every later visit to the page pay for one release’s marketing.

Screenshot craft

The screenshots themselves have rules, and most of them are about respect for the reader’s time and data:

  • Crop to the change, keep one landmark. A full-window screenshot where the new button is forty pixels wide makes the reader hunt. A crop so tight there’s no context makes them ask “where is this?”. Include exactly enough surrounding UI to orient — one toolbar, one heading.
  • Seeded demo data, never customer data. Screenshots are a well-documented leak channel: real names, real revenue, real email subjects in the corner of a “quick” capture. Keep a demo workspace with plausible fake data and screenshot only there. Blurring after the fact is not a policy; it’s a hope.
  • Match your product’s default theme and keep it consistent across entries, so the archive doesn’t strobe between light and dark. (If you ship themes or components, show both — that’s the one case where two screenshots of the same thing earn their bytes.)
  • Alt text states the change. “The export button, now in the editor toolbar” — not “screenshot”, not the filename, not empty. If you can’t write the alt text, you don’t know what the image is for, which is worth noticing.
  • Compress like you mean it. Capture at 2x for sharpness, then get the file into the tens-of-kilobytes range. A changelog page is an archive that only grows; sixty entries times two megabytes is a page nobody scrolls twice.

Motion etiquette

An autoplaying loop is the single most distracting thing on any page — human peripheral vision is built to notice movement, and it will keep noticing your GIF the entire time someone is trying to read the entry below it. So motion carries extra obligations:

  • Prefer a muted looping video to a GIF: smaller, pausable, and it can be stopped for readers whose systems ask for reduced motion. Honor that preference — an animation that can’t be stopped is an accessibility failure, not a flourish.
  • Keep loops short and self-contained — five to ten seconds, one idea, with the interesting moment visible for long enough to register. Nothing important may exist only in the final frame.
  • No sound, ever, in a timeline. If a walkthrough needs narration, it’s a demo video; link it. And caption it — anything with speech needs captions before it needs color grading.
  • One moving thing per entry. Two competing loops in one viewport means neither gets watched and the text gets skipped.

Your channels are text-first

Whatever you embed, remember where entries actually get read. The in-app widget panel is a few hundred pixels wide. Email clients block images until the reader opts in. Feed readers proxy them, resize them, or strip them. Chat notifications reduce the entry to a title and a permalink. A markdown export is pure text. The page — the one surface that renders your visuals faithfully — is one channel among many, which is the practical reason the text has to carry the fact. Write the entry to survive every channel; let the page be where it looks best.

Screenshots age — and here, that’s fine

In documentation, a stale screenshot is a bug: it teaches the old UI in a document that claims to describe the current one. A changelog is the opposite kind of document — every entry is dated, and the screenshot is a record of what shipped that day. When you redesign next year, don’t go back and retake old entries’ images; you’d be falsifying the record (and signing yourself up for unbounded maintenance). The one thing old media does owe you is restraint about weight: images below the fold should lazy-load, and a long archive should paginate rather than make one page carry five years of pixels.

Anti-patterns

  • The decorative hero. A stock illustration or brand-colored banner on every entry, whether or not anything visible changed. It says “marketing wrote this” and trains readers to scroll past images — including the ones that matter.
  • The GIF of text. Animated terminal sessions and cycling taglines force everyone to read at your chosen speed, which is wrong for every single reader. Text goes in text; a code block beats a screen recording of typing.
  • The eight-megabyte shrug. A giant recording attached to a change a cropped screenshot would have shown. Weight should scale with what the medium adds, not with how easy your capture tool made it.
  • The screenshot-only entry. An image and a “✨” where the sentence should be. Invisible to search, screen readers, and every text-first channel above.
  • Customer data in the corner. The support inbox screenshot with real subjects; the dashboard with real company names. Once it’s in a feed, it’s archived by readers you can’t reach.
  • Audio-only facts. A linked video where the deprecation date is spoken but never written. Anything decision-relevant appears in the entry text, full stop.

Where Wakelog fits

Wakelog entries are markdown, and the image syntax ![alt](https://…) works everywhere entries render — public page, permalinks, and the embed widget. Images are https-only and lazy-loaded with async decoding automatically, so a long archive doesn’t pay for pictures it hasn’t scrolled to. Honest caveats: Wakelog doesn’t host images — there are no uploads, so screenshots live on your own site, CDN, or object storage, referenced by URL (keep those URLs stable, or your history quietly loses its pictures). And the text-first rule above is enforced by reality here too: your RSS and JSON feeds carry the entry HTML, but readers decide what to do with the images, and chat notifications carry the title and permalink only. Write entries that stand on their words; add pixels where they demonstrate something.

Start your changelog — free   Next: changelog page design →

Related guides

Last updated 2026-07-31 · All guides