Episode 079 Deep Dive: The Evolution of Design System Documentation with Ben Callahan and Afyia Smith

Ben Callahan is joined by Afyia Smith, a content designer and technical writer who spent five years as a documentation specialist on the design system team at Epic Games, built AI readiness frameworks and governance models there, and now collaborates with PJ Onori on the DSDS documentation spec. Together with the community, they dig into who owns design system documentation and what changes when agents start reading it.

The survey went to more than 1,100 design system practitioners and drew 61 responses across five questions. The conversation covers machine readable versus machine parsable formats, recipes and gotchas files, decision trees for agents, the split between reference and guidance documentation, just-in-time docs, and whether AI should be writing documentation at all.

Show Notes
00:07 — Welcome to the Episode 079 deep dive
00:40 — Afyia's path into design system documentation
02:25 — Five years as a documentation specialist at Epic Games
03:50 — Emailing PJ Onori to contribute to DSDS
06:21 — This week's five questions, 1,100 sent, 61 responses
09:18 — Breaking down the responses that chose "other"
10:15 — Everyone figuring agentic workflows out on their own
11:04 — Looking for a correlation that isn't there
12:56 — Robin Di Capua on encoding compositional do's and don'ts
14:24 — Patterns, templates, and recipes in the DSDS spec
18:08 — Doug Neiner on recipes and gotchas files
19:16 — Kelby Gassman on docs turning into decision trees
23:52 — Kevin Coyle on machine readable versus machine parsable
26:09 — Surface-level delivery versus foundational content
27:04 — Stephen Greco on moving from Markdown to JSON and YAML
29:27 — Robin Di Capua on keeping prose alongside structured data
30:56 — Stephen Greco on reference documentation versus guidance
34:05 — Question five: humans, machines, or somewhere between
35:54 — Doug Neiner's Kindle and recipe book analogy
37:14 — Shaun Bent on two clients at opposite extremes
38:41 — Afyia on not picking a side
42:30 — Hattie Tadsen on meeting people where they are
44:02 — Just-in-time documentation as the goal
45:28 — Doug Neiner on AI-generated docs and false productivity
46:22 — Afyia: don't use AI to write the docs
47:19 — Hattie Tadsen on AI-assisted first drafts

Where to Find the Hosts
Ben Callahan is Founder of Sparkbox (https://sparkbox.com) and Redwoods Design System Community (https://bencallahan.com/redwoods). Read his writings, have him present at your event, or engage with him as a coach or consultant at https://bencallahan.com

Afyia Smith is a content designer and technical writer focused on design system documentation, governance, and knowledge architecture. Connect with her: https://bit.ly/4vVUhNP

Get the Raw Data
Access the complete survey data from Episode 079 to conduct your own analysis: https://bit.ly/4yV4JrD

Review the FigJam Notes
Dig into the collaborative notes we took as a community during the deep dive: https://bit.ly/4gismBZ

Join the Conversation
The Question explores design systems topics through community research and deep-dive discussions. Participate in future episodes and contribute to the next survey: https://bit.ly/answerTheQuestion