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

Episode 079 Deep Dive: The Evolution of Design System Documentation with Ben Callahan and Afyia SmithBen 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 draftsWhere to Find the HostsBen 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.comAfyia Smith is a content designer and technical writer focused on design system documentation, governance, and knowledge architecture. Connect with her: https://bit.ly/4vVUhNPGet the Raw Data Access the complete survey data from Episode 079 to conduct your own analysis: https://bit.ly/4yV4JrDReview the FigJam Notes Dig into the collaborative notes we took as a community during the deep dive: https://bit.ly/4gismBZJoin the ConversationThe 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/answerTheQuestionMusic licensed through Soundstripe.Code: C1COHEMFO6L4XE0H