Episode 079 Recap: The Evolution of Design System Documentation with Ben Callahan and Afyia Smith
Ben Callahan and Afyia Smith, a content designer and technical writer specializing in design systems, recap what the community said about who owns documentation and where docs are headed now that machines are reading them too.
The survey went to more than 1,100 design system practitioners and drew 61 responses across five questions. The conversation covers the shift from prose to structured content, the case for a dedicated documentation owner, the design system knowledge architect role, the DSDS spec work with PJ Onori, and the fourteen respondents who said machines will be the only future readers of their docs.
Show Notes
00:00 — Welcome and introductions
00:14 — Black-and-white prints and a giraffe collection
01:00 — Almost 80 episodes, and the first one on docs
01:24 — Survey setup: 1,100 practitioners, 61 responses
02:34 — Afyia answers the open-ended question herself
02:41 — Documentation as a knowledge layer, not just content
03:20 — Focused ownership and just-in-time documentation
04:08 — What docs looked like in the early design system days
04:30 — Bare, scattered, outdated, ungoverned
06:17 — The case for a point person
07:53 — The design system knowledge architect role
08:20 — Coming back a year later to the same mess
11:03 — Question one results: who owns documentation
11:57 — By design or by default?
12:24 — Digging into the 30% who answered "other"
13:36 — Question two: everyone figuring agentic workflows out alone
14:24 — The correlation that wasn't in the data
15:00 — Question three: reporting on agentic workflow success
16:07 — Ownership reveals visibility more than success
17:00 — Machine readable versus machine parsable
17:20 — Surface-level changes versus foundational ones
17:49 — Bad docs surfaced everywhere are still bad docs
18:49 — Working upstream of AI
19:38 — The component schema work with PJ Onori
20:45 — DSDS, doc origin, and metadata as a trust layer
23:32 — Question five: writing for humans, machines, or both
24:48 — What we would lose without human-readable reference sites
26:48 — Why documentation has always been the passion
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
Music licensed through Soundstripe.
Code: C1COHEMFO6L4XE0H