Skip to content

Docs: Add screenshots, demo GIF, and live demo to README #4

@alohays

Description

@alohays

Summary

The README is 124 lines of pure text — zero screenshots, no demo GIF, no live demo link. For a visual dashboard product with maps, real-time panels, and data visualization, this is the single biggest missed opportunity for GitHub star conversion.

Why This Matters

GitHub browsing research shows users spend 3-7 seconds scanning a README before deciding to star or leave. For visual projects, the hero image is the #1 conversion factor.

  • WorldMonitor (25K+ stars, the cited inspiration): leads with visual preview
  • Grafana, Uptime Kuma, Netdata: all have screenshots above the fold

Claims like "MapLibre GL + deck.gl with 5 layer types" and "6 panel types" are unverifiable without visuals. A potential user cannot imagine what this looks like.

Action Items

  • Deploy a live demo on Vercel (free tier) with geopolitics-full preset (globe projection, entity tracker, instability index — most visually impressive)
  • Take screenshots of 2-3 presets showing the dark-themed map with sidebar panels populated with real data
  • Create a 15-second animated GIF showing: map loading → news data populating → AI brief generating → layer toggle interaction
  • Add a hero image at the top of README.md, before "What is this?" section:
    <p align="center">
      <img src="docs/screenshots/hero.png" alt="monitor-forge dashboard" width="800">
    </p>
  • Add a prominent "Live Demo" badge/link in the README header
  • Consider adding preset-specific thumbnails to the preset comparison table

Files

  • README.md — hero image, demo link, screenshot embeds
  • New directory: docs/screenshots/ — hero image, preset screenshots, GIF
  • Vercel deployment (operational task, not code)

Dependency

Blocked by the first-run experience fix (#2) — need a working dashboard to take screenshots from.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationpriority: criticalMust fix before public launch

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions