Dennis Dawson - Graphic Relief: Beyond Flowcharts and Screenshots

Documentation fails most often when it’s written for the author’s convenience, not the reader’s job. Dennis Dawson’s core finding is that technical docs become usable—and measurably more effective—when they’re reorganized around navigation, “decision layers,” and modular, runnable learning paths, then validated through task-based testing rather than praise.

Dawson’s turnaround story starts with a new role at Ripple, where existing documentation was thorough but dense: long walls of text, too many links, and no clear “just enough” path for beginners. He stopped trying to read everything and instead learned by using the software with sample code and engineer support. From that experience, he built a habit of capturing what he learned in digestible form and sharing it with newcomers—then iterating based on feedback. The next hurdle was visual: users liked his drawings, but corporate style concerns threatened to erase them. Working with designers Ellen Yang and Natalya Sabari, he translated his whimsical, metaphor-driven illustrations into a reusable “neon” graphic system that still followed corporate color guidelines.

The transformations he implemented over the following year were guided by conference lessons on layered thinking (especially the missing “decision layer”), and by multimedia learning research from Richard Mayer’s book Multimedia Learning, which gave him both vocabulary and scientific justification for changing visuals. The practical changes were concrete: navigation cards on main and sectional landing pages; a new introduction that explains high-level concepts without drowning readers in detail; more whitespace and scan-friendly layouts; and consistent, metaphorical illustrations that help readers grasp concepts at a glance.

Crucially, Dawson restructured tutorials to reduce context switching. Earlier tutorials mixed conceptual explanations with development tasks, forcing readers to jump between “user hat” and “developer hat” every paragraph. He compared this to a painful interface where form design and programming logic were constantly interleaved—an experience that caused real headaches and ultimately led to a redesign. His solution borrowed from how O’Reilly-style developer books work: modular lessons that build sequentially but can be started anywhere, with isolated user interface from business logic. That modularity lets developers copy self-contained best practices and methods directly into their own applications.

For videos, he recommends demos that clarify background processes through animation and inline commentary, while avoiding “typing then running code” as a dull default. He also revises flowcharts so sections are visually self-contained—using builds (like slideshow-style stepwise reveals) so readers don’t scroll back and forth between distant explanations.

Finally, Dawson treats testing as an evidence engine. He describes three tiers: informal co-worker review, external task-based feedback, and—when possible—bringing in a testing consultant to run structured usability sessions. The goal isn’t compliments; it’s watching people struggle with real tasks without excessive hints. One participant’s failure to find a key navigation element (“spin the triangle”) pinpointed an interface problem, while other criticisms validated that the new graphics and video direction were landing.

Across the talk, Dawson’s advice is blunt: write for skimmers and doers, simplify language, justify parameter choices with rationale, avoid jargon and “fishing” for understanding, and treat documentation as never-finished—shipped, then improved. The result is documentation that looks friendlier, reads faster, and performs better under real use.