storytelling-with-data

Files (7)

• README.md
• SKILL.md
• chart-selection.md · references/
• colour-and-emphasis.md · references/
• hooks-and-moments.md · references/
• narrative-frameworks.md · references/
• review-checklist.md · references/

SKILL.md (first lines)

# Storytelling with Data (SWD) Skill

Apply the 6-lesson SWD framework from Cole Nussbaumer Knaflic for visual and design decisions, combined with narrative storytelling frameworks (Dykes, Duarte, Miller, Dicks, Cron, Heath) for structuring compelling stories that drive action.

> **Format-agnostic by design**: This skill covers _what_ to communicate and _how_ to design it. Pair it with format-specific skills that handle output mechanics (e.g. pptx skill for slide decks, a web framework for dashboards).

---

## The SWD 6-Lesson Framework

Every data communication task should be evaluated against these 6 lessons, applied in order:

### Lesson 1: Understand the Context

Before touching any tool, answer three questions:

1. **WHO** is your audience? What do they care about? What's their relationship to you? What will motivate them?
2. **WHAT** do you need them to know or do? Define the single action or takeaway.
3. **HOW** will you communicate? Live presentation? Email? Dashboard? This changes everything about design.

**Key techniques:**

- **The 3-Minute Story**: Can you explain your entire message in 3 minutes? If not, you haven't distilled it enough.
- **The Big Idea**: One sentence that articulates your unique point of view, what's at stake, and what you want the audience to do. Format: [situation] + [complication] → [recommended action].
- **Storyboard first**: Sketch your flow on sticky notes or paper before opening any tool. Rearrange freely.
- **Exploratory ≠ Explanatory**: The audience sees only the _explanatory_ output - the curated insight, not the full analysis journey. Never dump exploratory analysis on your audience.

**When reviewing existing work, ask:**

- Is there a clear "so what?" on every chart, panel, or section?
- Could the audience state the key message after a 3-second glance?
- Is there a specific call to action?

### Lesson 2: Choose an Appropriate Visual Display

Match the visual to the message. You can handle the vast majority of business communications with just a few chart types.

**Read `references/chart-selection.md` for the detailed chart selection guide.**

Quick decision framework:

- **Comparison across categories** → Horizontal bar chart (default workhorse)
- **Trend over time** → Line chart (continuous) or vertical bar chart (discrete periods)
- **Part-to-whole** → Stacked bar or waterfall (NOT pie charts)
- **Two data points comparison** → Slopegraph
- **Single important number** → Simple text (the number itself, large, with context)
- **Detailed lookup** → Table or heatmap

**Charts to AVOID:**

- Pie and doughnut charts (hard to compare areas/angles accurately)
- 3D anything (adds clutter, distorts data, makes reading values harder)
- Dual y-axes (confuse the audience about scale relationships)
- Spaghetti graphs (too many overlapping lines - filter or use small multiples instead)

### Lesson 3: Eliminate Clutter

Clutter is any visual element that takes up space without adding understanding. Every element increases **cognitive load** - the mental effort to process information.

**Identify and remove:**

- Chart borders and unnecessary outlines
- Gridlines (reduce to light or remove entirely)
- Data markers on every point (only mark what matters)
- Redundant labels (if the axis says it, the data label doesn't need to)
- Bold/italic/colour on everything (when everything is emphasised, nothing is)
- Legends (can you label directly instead?)
- Rotated text (hard to read - restructure the chart instead)
- Decorative elements that don't encode data

**Apply Gestalt Principles to structure what remains:**

- **Proximity**: Group related items close together; separate unrelated ones
- **Similarity**: Use consistent colours/shapes for items in the same category
- **Enclosure**: Subtle backgrounds can group related content
- **Closure**: Remove unnecessary borders - the eye fills in gaps
- **Continuity**: Align elements so the eye flows naturally
- **Connection**: Lines connecting points imply sequence or relationship

**Decluttering process (step by step):**

1. Remove chart borders
2. Remove or lighten gridlines
3. Remove data markers (unless specific points need emphasis)
4. Clean up axis labels (round numbers, remove unnecessary precision)
5. Label data directly (eliminate legends where possible)
6. Use consistent, strategic colour

### Lesson 4: Focus Your Audience's Attention

Use **preattentive attributes** - visual properties the brain processes before conscious thought - to guide the eye to what matters:

- **Colour**: The most powerful tool. Use a single accent colour to highlight the key data; push everything else to grey. Never use colour decoratively.
- **Size**: Larger elements draw attention first. Make the key number or data point bigger.
- **Position**: Items at the top-left get seen first (in left-to-right reading cultures). Place the most important information there.
- **Bold/weight**: Use sparingly on text to create hierarchy. Bold the key phrase, not the whole paragraph.

**The Grey + One Colour rule**: Default everything to grey, then use ONE strategic accent colour to highlight the story. This is the single most impactful SWD technique.

**Read `references/colour-and-emphasis.md` for the emphasis hierarchy and grey-plus-accent strategy.** This skill owns the message and emphasis strategy; for the visual rendering and colour system (validated palettes, mark specs) defer to the dataviz skill.

**Memory matters:**

- **Iconic memory** (~0.5 seconds): Preattentive attributes are processed here - that's why colour and size pop instantly
- **Short-term memory** (~4 items): Don't overload a single view with too many competing elements
- **Long-term memory**: Connect to what the audience already knows - use familiar chart types and conventions

### Lesson 5: Think Like a Designer

Design serves the message. Apply these principles:

- **Form follows function**: Every element earns its place by serving comprehension
- **Affordances**: Make interactive elements look clickable; make important text look important
- **Accessibility**: Would this work in greyscale? For colour-blind audiences? Without a narrator explaining it?
- **Aesthetics build trust**: Clean, well-aligned visuals signal competence and credibility

**Practical design rules:**

- Use consistent alignment (create an invisible grid)

From sammcj/agentic-coding, Apache-2.0.

More from sammcj/agentic-coding