ABCDEFGHIJKLMNOPQRSTUVWXYZ
1
Thanks for your interest in The Question!

Sign up to participate in future questions here.

This file is the raw data from Episode 079, deep dive hosted on August 6, 2026 with Ben Callahan and Afyia Smith.

There are 61 answers. The question this week was:

-----

Hello, system thinkers!

Last week, Afyia Smith and I were talking about design system documentation. In that convo she said, "Documentation is owned by everybody, which means it's owned by nobody." I know I’ve felt this pain, and it’s clear she has too.
Afyia led content design and documentation strategy for enterprise design systems at Epic Games. She dreams about governance frameworks, taxonomy, information architecture, and (of course) structured content. When I asked her about her experience in the field, she had some opinions :)

“Documentation has never quite gotten its rightful place in our world. We treat design and code as the system, and docs as the thing we'll clean up later. But docs are the house the system lives in. They're the entry point, the binding force, the reason a new person can find out what already exists instead of building it again.” (Afyia’s words, paraphrased by me!)

And, we dug into what is changing about docs in the DS space…Good docs used to mean clear, consistent, accurate, human-readable. That's still true, but it's no longer enough. Now they also have to be machine-readable: structured, explicit, less ambiguous, and tailored for an audience that isn't only a person. Afyia and others are building schemas for just this purpose.
With all of this as context, we’re wondering if the fact that machines now need the docs will finally force us to give them their rightful place on our teams or just make the cost of ignoring them harder to hide.

This week, we want to dive into how design system documentation is owned, evolving, and working. Welcome to Episode 079 of The Question, with Ben Callahan and Afyia Smith!

--

Who owns design system documentation for your organization? (Select one)
• A dedicated content designer or technical writer
• A designer on the system team
• An engineer on the system team
• The design system lead or manager
• Everyone contributes, no clear owner
• N/A or Other (please explain)

Who owns product-building agentic workflows for your organization (context files, agent instructions, skills, MCP, harnesses)? (Select one)
• Someone on the system team
• Someone not on the system team
• A cross-discipline working group
• Everyone is figuring it out on their own
• Nobody
• N/A or Other (please explain)

How would you describe the success of product-building agentic workflows at your organization? (Select one)
• Not successful
• Somewhat successful
• Highly successful
• No way to know
• N/A or Other (please explain)

In the last 12 months, what have you changed about your documentation? (Select all that apply)
• Restructured content into a consistent schema or template
• Added machine-readable formats (JSON, frontmatter, structured data)
• Written context files or agent instructions
• Made language more explicit and less ambiguous
• Nothing
• N/A or Other (please explain)

What does the future of design system documentation look like for you/your organization?
2
Question 1: Who owns design system documentation for your organization? (Select one)Question 2: Who owns product-building agentic workflows for your organization (context files, agent instructions, skills, MCP, harnesses)? (Select one)Question 3: How would you describe the success of product-building agentic workflows at your organization? (Select one)Question 4: In the last 12 months, what have you changed about your documentation? (Select all that apply)Question 5: What does the future of design system documentation look like for you/your organization?
3
The design system lead or managerEveryone is figuring it out on their ownSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsWe've made 'ai-friendly' versions of component documentation (basics like available props, do/dont's) but I'd like to extend it with more design guidance and also build similar files for content guidelines and ux patterns.
4
Everyone contributes, no clear ownerEveryone is figuring it out on their ownSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or template,Written context files or agent instructionsDefinitely more agentic and machine readable documentation. More context around decisions made and why, hosting changes allowing AI better ability to find what it needs beyond just searching in a document, and adding more documentation around changes in the system for agents to help with migrations for end users.
5
Everyone contributes, no clear ownerSomeone on the system teamHighly successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or templateI think the information extraction can be automated from the system itself but the interpretation and curation of that information is best still left to humans. Although in working with my clients I suspect that a lot of orgs are going to try and automate documentation and say job done just because the page is filled.
6
The design system lead or managerI’m not sure anyone specifically own these, but there are folks experimenting with AI Not successfulI’m still working on writing documentation. There was none for our style guides when I started, so I’ve been trying to define it as I built our system. Queryable and integrated with a slack assistant.
7
The design system lead or managerSomeone on the system teamSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsIt’s AI-centric for agents to build with the system and communicate documentation summaries and answers to humans.
8
The design system lead or managerNobodyNo way to knowMade language more explicit and less ambiguous,Updating component documentation stickersheets, moving documentation notes that apply to completely within figma. Keeping the separate documentation split to be in sections such as onboarding (basic understanding of a design system and why it matters) and how to implement. Overall design standards have their own section.Since my company is now adopting design systems across different teams the documentation had to shift from being singular about the mobile design to being split into sections that can be digested by the whole company and templates for product specific design systems.
9
The design system lead or managerEveryone is figuring it out on their ownNo way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Written context files or agent instructionsUsing one system as a source of truth and trying to automate/spread that information into different platforms and resources
10
Everyone contributes, no clear ownerWe do not address LLM workWe do not address LLM workNothing-
11
Everyone contributes, no clear ownerA cross-discipline working groupHighly successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsWe're mid-transition, attempting to move off a legacy Google Site and toward a single source of truth that will power machine-readable and human readable docs. At the same time, we're aiming to reduce ambiguity in the documentation and hardening a subset of our guidance into a rules registry that will govern agent and human design output.

For us, the future is having documentation at your fingertips when/where you need it, and seemlessly integrated into the generative tools that we believe our industry is marching towards.
12
The dedicated design systems team (currently, 2 designers, 3 engineers). No one outside of the DS team.Everyone is figuring it out on their ownNot successfulMade language more explicit and less ambiguous,Written context files or agent instructionsThe same way it should have always looked: constant iterative improvement. Working to right-size and properly locate documentation to ensure that the information is digestible, clear, and easy to access for all users.
13
Generally the designer who worked on the component/ui creates the docs page in Figma. Then the developer who wrote the code creates the docs page and fills out the technical parts.Everyone is figuring it out on their ownNo way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or templateReally not sure. Some product developers are asking if we can get rid of the design system now that agents can write code with our tokens... I think that's incredibly short-sighted, but if the higher ups think it's a good direction, there isn't much we can do.
14
The design system lead or managerA cross-discipline working groupSomewhat successfulMade language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsIt's still very human-first in our org, but we are intentional with our integration of AI. As of now, it helps to police our code hygiene.
15
Everyone contributes, no clear ownerEveryone is figuring it out on their ownNo way to knowRestructured content into a consistent schema or templateMore agnostic that can be used with any tooling.
16
Everyone contributes, no clear ownerEveryone is figuring it out on their ownNo way to knowMigrating navigation to a new service which will hopefully allow for more AI readabilityAn MCP that users can ask question directly to and it can be answered using our documentation
17
A designer on the system teamEveryone is figuring it out on their ownNo way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsI’ve been actively working on this and trying to figure it out. I am moving all our documentation into the design system repo and storybook, and trying to make this info readable by the consuming teams’ Claudes (while still human readable in Storybook). I’ve been running some AI audits on our system, and that’s been pretty helpful in identifying gaps. This is a great topic and I look forward to hearing from others what they are doing. No one else is really working on our DS documentation, so I guess I own it.
18
The design system lead or managerEveryone is figuring it out on their ownNot successfulRestructured content into a consistent schema or template,Written context files or agent instructionsOnce we finally get to one source of truth, then we'll see how AI reacts to it and adjust or add specific AI resources as needed (beyond the initial component creation instructions).
19
Everyone contributes, no clear ownerEveryone is figuring it out on their ownNo way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsCurrently we are rewriting our documentation site due to a host of issues (non-ai related). However, with that, we will be building in an ai-compatible format that reduces the token cost of pulling data from our documentation site.
20
Everyone contributes, no clear ownerEveryone is figuring it out on their ownNo way to knowNothingSadly the future looks more like the past. There is a desire for improvement, but there is no action. Everyone is "succeeding elsewhere".
21
Implementation-specific docs are owned by that implementation's eng team (React, web components, Android, iOS, etc.). Design docs are usually owned by the design team, but often with help from a content strategist.The system team, but not one specific person. Everyone on the team contributes as needed.Somewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or template,Written context files or agent instructionsSome efforts are being made to collect varying sources of documentation (for varying implementations) into one place, which could be very helpful. For my team's specific implementation, as we do a major redesign on our system, we are also making it more AI-friendly for consumers and also for our team. AI writes a large amount of our documentation and there are a number of rules and skills dedicated to keeping documentation looking and feeling consistent throughout.
22
A designer on the system teamEveryone is figuring it out on their ownSomewhat successfulWritten context files or agent instructionsWe are going to keep leaning into making it more parsable by agents. So far what is needed for agents has highlighted gaps in our human facing documentation and training.
23
Everyone contributes, no clear ownerAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsTrying to make it more readable for AI.
24
Everyone contributes, no clear ownerEveryone is figuring it out on their ownNo way to knowRestructured content into a consistent schema or templateLikely be more AI generated and maintained.
25
I (as the dedicated content designer) tell people I own the shape, structure, and scale; you (the product designer at the front lines) own the product truth. So we own it together. We are each accountable to our pieces.Someone on the system teamSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or templateI'm preaching #NoLatentInfo, a term a UXE buddy used and I've glommed onto. If you're writing something down, it's important enough to make that info actionable, instead of waiting for someone to stumble upon it and decide to action on it themselves.
26
Everyone contributes, no clear ownerSomeone on the system teamSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsNot quite sure but we are certainly augmenting the existing documentation to be more agent friendly 🤖
27
Everyone contributes, no clear ownerEveryone is figuring it out on their ownWe haven't really started utilizing this a lot because we don't have a design system in code to work off of.Restructured content into a consistent schema or templateNot sure! we are still defining it :)
28
It depends. If it's a team that developed the original component or pattern, they author it, but it's then owned by the system team.It's complicated.No way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsIt's a pile of markdown files with the hope that that can evolve into skills. I have teammates who are building out more complex skills that involve business rules they've used to generate entire interfaces, but that's more the exception than it is the rule.
29
The design system lead or managerEveryone is figuring it out on their ownNo way to knowMade language more explicit and less ambiguousI'd like to put effort into making and maintaining more agentic workflow documentation, but we are waiting to see what a new cost era settles into as we know changes are coming. Our institution is supposed to change from unlimited to token allotments in Sept. This keeps me from diving too deep into figuring out sustainable ways to create documents for humans and machines. I won't know if agent usage will tank after they start limiting us, or if they'll devise some other way to support a growing cost internally.
30
The design system lead or managerEveryone is figuring it out on their ownNo way to knowNothing,Opened an MCP server to reference it, but have not changed the content or writing style. There is a desire to expand documentation beyond just the design system (aka all shared components). We use Supernova today but I could see us wanting to move off of that platform as well for something that is opensource and free. Supernova also limits the editor seats so that would be something that would need to change.
31
Everyone contributes, no clear ownerEveryone is figuring it out on their ownNo way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Written context files or agent instructionsWe still primarily rely on humans reading docs and training teams to look at our doc site instead of Figma and Storybook. Our goal is to also ensure it’s AI readable but we don’t yet have agents building. We use ZeroHeight which has some of that support built in but I do wonder if we will continue using in the future as the barrier to creating custom docs is now much lower.
32
The design system lead or managerUnsure - don’t have view into how all teams are doing this. Somewhat successfulRestructured content into a consistent schema or template,Written context files or agent instructions.ml files and a website
33
The design system lead or managerEveryone is figuring it out on their ownSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or templateI'm not quite sure but we're prioritizing markdown files for each component and DS foundations elements right now with the plan to convert to json for a mcp. I think the user friendly version is where I'm getting a bit stuck, is this still needed? Who will use it?
34
The design system lead or managerEveryone is figuring it out on their ownSomewhat successfulWritten context files or agent instructionsTrying to optimize best we can
35
The entire GoFundMe design system team (designers and engineers).As it relates to systems, it's the GoFundMe design system team. More broadly, everyone is figuring it out on their own and sharing with each other. Highly successfulWe’ve connected agents to our docs via a custom MCP and write differently because agents are readers too (less imagery, for example). We also use our CMS’s MCP to ship docs faster.

A lot is still out of date, so we’re considering re-architecting the site so agents can help maintain it. We also want new ways to consume docs with more visual context, since people build more in code and less in canvas tools.

We’ve built a playground with our real design system components too. It’s not classic documentation, but it partly replaces the need for it: people can see what an agent does with the real components instead of reading about them.		For us, the future of design system documentation is agent-native: written for humans and agents, kept current by agents, and consumed through interactive, code-first experiences rather than static pages.
36
The systems team, but designers and engineers all contribute. Design owns usage and overview for each component, engineers own implementation details for their platforms (iOS, Android, Web). A few different groups who are loosely aligned at the moment. We're currently working on tighter alignment across all these efforts. No way to knowWe're in the middle of building consistent schemas, machine-readable formats, and connecting it all to a knowledge graphIdeally, I'd love to use the schema Afiya and PJ are working on to drive a custom doc site, MCP, CLI, etc to provide documentation context to designers, engineers, and agents.
37
The design system lead or managerEveryone is figuring it out on their ownNot successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructions,We’ve been experimenting with AI-assisted documentation workflows, using Claude to generate documentation from a standardized template and create reusable agent instructions. The goal is to make our design system documentation more consistent, scalable, and useful for both humans and AI.We don’t yet have a mature design system, so documentation is still evolving. Looking ahead, I think documentation needs to become more structured and machine-readable so it can support both designers, developers, and AI-assisted workflows. For large organizations, a well-maintained design system and documentation are becoming prerequisites for AI to deliver on its promises, rather than something AI can replace.
38
Everyone contributes, no clear ownerA cross-discipline working groupSomewhat successfulMade language more explicit and less ambiguous,Written context files or agent instructionsWe are now writing the docs with AI in mind, one simple exmple is to caption diagrams with full descriptions so that there is enough context in the words instead of relying on understanding the images.
39
2 designers of the system team, and the content design teamEveryone is figuring it out on their ownNot successfulAdded machine-readable formats (JSON, frontmatter, structured data)An AI agent. Users of our design system, particularly designers, are constantly asking targeted questions via support channels and private messages rather than searching through full documentation. This pattern reflects a clear shift toward conversational, agentic interaction.
40
The design system lead or managerSomeone not on the system teamI wanted to answer No Way to Know but it's more like "No One Tells Us". We'd already struggled with inclusion in the product flow, and since AI integrations, our involvement lessened even more. Our only way to know what's happening is sprint reviews which is too late to help, catch, or remedy anything.

I know they're generating UIs, but I have no idea how accurately they're being made, or how efficiently, or whether hallucinations are making their way into production code. So there's no NO way to know, but our non-involvement means it's more we are just left out of the loop.		Nothing,AI hit in the middle of some already hefty work for our 2 person dev team. I've started looking into spec generation but it's tough in the middle of component work with our team size and distributed focus.Improving storybook with more stories and less written docs, split design and dev docs for better disciplinary focus areas, and component metadata.
41
The design system lead or managerA bit of a mixture of everyone's figuring it out on their own and a few people who just got AI Enablement focused roles on the Design System team a few months ago.Somewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Written context files or agent instructionsSome managers have strong feelings about the documentation being readable and accessible by humans, but in the same breath mention how people don't read.

I don't disagree about having a centralized source of truth that can be referenced or linked when questions or issues arise, but it needs to be predictably set up and searchable that people (and AI) can find what they need.

We still need to think about the experience and ensure understanding especially when (not if) AI gets it wrong.
42
The whole DS team owns the docs when they work on specific thingsWe have a team that used to be DS Tooling and is now UXAI. They have been driving AI prototyping aligned to the DS with knowledge of the DS from their time working on it and they partner with us (Im the design manager for both DS and UXAI so also provide a common thread in my role)Somewhat successfulWritten context files or agent instructionsNot sure but we are diving into more global and local patterns so were working through how docs evolve to support that kind of depth of design
43
The design system lead or managerno one owns it because we aren't doing itnot doing itwe planned an entire overhaul of our documentation to make it more concise and human centeredusing AI to create documentation for humans
44
A dedicated content designer or technical writerSomeone on the system teamHighly successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsWe continue to ensure that documentation works well for both humans and robots. We did a lot of work last year to revamp our docs, not for AI, but because our consumers needed us to. That will continue to happen, and if anything, structuring docs for AI use is forcing us to make a lot of the implicit, explicit, which is good for humans too.
45
The documentation is owned by the systems team, design, engineering, and content design, not by a specific discipline or person.Someone on the system teamHighly successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or template,Written context files or agent instructions,Created an MCP server for the DS, which consumes the documentation and uses it to provide guidance to agentsMore documentation is moving into code and other surfaces, such as the documentation website, using code as the source of truth.

I think documentation will continue to evolve to support agents as a primary audience, with humans becoming a secondary audience.
46
Everyone contributes, no clear ownerA cross-discipline working groupUnsure just yetWritten context files or agent instructionsWe want it to still be a good balance of what both machines need and humans need. We also just want to keep adding more and more.
47
The DS team owns it and members of the team collaborate on itSomeone on the system teamI just started so I don't know yetAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or template,Written context files or agent instructionsDocumentation will become more than just paragraphs of texts with code snippets and pictures. It will become its own product where governance, evals, structured data, design decisions etc. will live and be available to machines and humans via tools (like MCPs, Figma plugins, web interfaces...)
48
Everyone contributes, no clear ownerSomeone on the system teamSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data)I imagine our documentation shifting to machine-readable first, and self-generating updates based on code contributions, with a a human in the loop to review.
49
The DS team owns the documentation; DS designers and engineers contribute to the same docs.A cross-discipline working groupHighly successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Add more clarity and structure to existing (Figma) Dev Mode annotationsMore baked-in context for design components; favor generated guidance (component description > AI > doc site) over rewritten, on-the-artboard guidance.
50
The DS team as a whole. Documentation is part of the acceptance criteria of every new component or enhancement to an existing component, so it is always current. Design system designers author design-related documentation in a Figma file and that gets pulled into our Storybook doc site via Figma APIs. Design system engineers author developer-related documentation as MDX files in Storybook.Everyone is figuring it out on their ownSomewhat successfulWritten context files or agent instructionsEnsuring our docs are as readable by agents as they are by humans.
51
Everyone contributes, no clear ownerA cross-discipline working groupSomewhat successfulI'm not sureMultiple formats and more consistency. It used to be edited by multiple people who didn't all follow the same format.
52
Teams close to the design system (designers, engineers)Everyone is figuring it out on their ownNo way to knowAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsIt'll continue to be the same even if teams don't use it like we (at large) think they do. I believe there's a need to rethink this, even before AI.
53
The design system lead or managerEveryone is figuring it out on their ownSomewhat successfulMade language more explicit and less ambiguousMore specific rules and includes design decisions to make
54
N/AN/AN/AN/AN/A
55
The design system lead or managerThe system team as a wholeSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or template,Written context files or agent instructionsCreating more agent first docs. Actively testing documentation to see how it works with agents and product teams, rather than the previous workflow of creating it once and releasing.
56
The design system lead or managerEveryone is figuring it out on their ownSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Restructured content into a consistent schema or template,Written context files or agent instructionsWe are working to mget it all into markdown files and in storybook. My role as DS lead will also include coding demos of components in the storybook. Shared ownership of some of the AI focused docs.
57
As product owner of the design system, I oversee the doc site as part of our product. I'm the governor of the site overall. However, we have a headless CMS so everyone on the design system team who has access can contribute content the areas they own. Our engineering team owns the code of the site itself. I frequently review our documentation to ensure it's following content guidelines, consistency, formatting and our agreed upon information architecture. For the design system itself, it's our design system product triad (UX/A11y, Engineering, Product) owns our agents and workflows. For our organization as a whole, there is work being done to organize governance and registry of agents and agentic workflows with a cross-functional team that is a part of infrastructure.Highly successfulWritten context files or agent instructions,We have a few agents we have built that we exported our documentation into context and instruction files. As part of that work, we also have incorporated change detection of our documentation that updates our instruction files for those agents to stay in sync with the latest.I don't think our documentation will change all that much in the future. I think we may add to our documentation site with more AI abilities, like updated search and chat functions. Overall, our documentation is a solid foundation for our product and the work we are doing.
58
Everyone contributes, no clear ownerEveryone is figuring it out on their ownThere is no "success" metric right now because, due to the complexity, size, and sensitive nature of our patient's health data, leadership is still figuring out how to safely begin even introducing AI into the org. Despite many employees, individually, having advanced AI knowledge, our org is still in the infant phase with AI, so those individuals can't even use the skills they have within the org's walls... yet.Written context files or agent instructionsI'll answer as an individual who doesn't like writing documentation on a DS team that does not have a dedicated role for such (not speaking for the whole org): I'd love to see automated initial creation--an agent that fills in a template and gets it 90% of the way there. We (DS team) then just QA the output. We never want to be fully "hands-off" though because some components, tokens, etc. will have a nuance or two that won't quite fit the template.
59
I'm outside the digital DS space right nowI'm outside the digital DS space right nowI'm outside the digital DS space right nowI'm outside the digital DS space right nowI'm outside the digital DS space right now
60
An engineer on the system teamA cross-discipline working groupSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsEveryone is using AI tools like Claude, Cursor and Copilot. Our strategy is to try and bring the documentation to where our users are at in these different AI tools. Our docs are already being consumed less and less by people, and we have found that most of users are just trusting their preferred AI tools.

For our org, documentation is starting to look like an AI first approach with human readable docs as a supplemental format. With that being said, we are building both the AI context and the standard docs site from the same source of truth, so there is little overhead. It is mostly about the content structure being more AI friendly and clear.

Our goal is that our documentation and guidance is just injected into people’s workflows as the default experience, without them ever really knowing.

Our organization sees documentation as more important than ever, things are getting generated at record levels. If we do not provide proper documentation and context, then problems will compound faster than ever before.
61
An engineer and designer on the design system team co-own documentationSomeone on the system teamHighly successfulMade language more explicit and less ambiguous,Written context files or agent instructionsWorking toward it becoming more automated with built in skills that can guide our system users with information, design intent, and catch issues or gaps.
62
Design for the design/branding guidelines, engineering for the technical/implementation guidelinesEveryone is figuring it out on their ownSomewhat successfulAdded machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Restructured content into a consistent schema or template,Written context files or agent instructionsThe future for us is having documentation that’s consumable by agents but still readable by humans. Right now we’re struggling with striking that balance and in my opinion, we’re structuring docs and adding extraneous information to our APIs in a way that’s confusing. I’m not sure there’s a clear solution to this yet though.
63
Everyone contributes, no clear owner. But there are 3 primary authors are our Chief Architect (engineering), one designer for patterns, one designer for components.Right now, ownership is split by default rather than by design. The design system team is building out the tools and context, but product teams are inventing their own in the gaps, including their own versions of design system context when we haven't provided what they need yet. Ideally those gaps would be signal: teams would contribute their interpretation back so we can prioritize what goes into a centralized skill. Instead, everyone's in survival mode, so we're not capitalizing on that gap identification as an org. And even where we do build the centralized version, getting teams to migrate off their homegrown one is its own fight.I'm honestly still skeptical. I don't hear much back from the product teams right now so it's not clear whether they are building the right solutions together or just moving fast in isolation, racking up debt without being thoughtful about what we're actually creating.Added machine-readable formats (JSON, frontmatter, structured data),Made language more explicit and less ambiguous,Written context files or agent instructions,Created a chatbot to answer design systems questions powered by the content in the documentation.Documentation needs to get more opinionated and more complete. Right now it often reads as a menu of options with no clear guidance on which one to actually use.

Two things would fix that. First, consistent examples across code, design, QA, and docs, built from our own products rather than generic use cases, so consuming teams see exactly how a component or pattern gets used in context instead of translating a generic example into their situation.

Second, documentation should cover the full picture: what a component (or pattern) is, its semantic purpose, when to use it over something that looks similar but serves a different purpose, and how to configure it for specific use cases. Right now it's too easy to reach for something because it's visually close enough, even when it's semantically wrong for the job.

Very curious to see how PJ Onori's documentation spec develops and how it can help us.
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100