The future of design system documentation
For episode one of DesignOps Island Discs season two, we sail to Chicago to talk to Chase McCoy, who currently works as a product designer on design systems at Stripe, having previously kickstarted the Seeds design system at Sprout Social. Off of the back of Chase's brilliant article on Design Systems as Knowledge Graphs, we talk to Chase about the future of design system documentation and how we're currently living in the 'bad timeline' of the internet.
- Chase on Twitter
- Design systems as knowledge graphs
- Seeds - Sprout Social
- Frank Ocean, Blonde
- Broad Band, Claire L. Evans
Luke: So to get started, I suppose you've been in design systems for a little while at both Sprout and at Stripe but what led you there? How did you get into the world of design systems in the first place?
Chase: Great question. I think I came into design systems in the way that a lot of folks do which is like being a hybrid designer-developer person. I feel like there's a lot of us that tend to focus on design systems, but I actually got my start in iOS development. I started as a mobile developer. I went to school for computer science, always being interested in design. But, knowing that designing wasn't enough for me, I wanted to take those things all the way and be able to deliver something to an end-user. And so I thought, I'll go to school, I'll learn programming, and I'll study design on the side and I'll be this hybrid sort of person.
So I went to school for computer science, learned that computer science, isn't actually all programming. It's a lot of theory and math and all of these things, which were super valuable, maybe a little bit less interesting to me and not maybe exactly what I was looking for, but very valuable. I learned a lot of how to learn and how to apply skills. But partway through college, I decided to do an iOS bootcamp. So I did a bootcamp, a 12-week program for iOS development. I had already been tinkering a little bit myself learning objective-C did this bootcamp switched to swift. I learned probably more in that 12 weeks. And I think I learned more of what I wanted to learn than I did in my entire college career. So I started doing that. I had a couple of apps in the app store and then near the end of my college degree, I got hired on to a part of my university, essentially a branch of my university that does application development for various agencies within the state of Mississippi, which is where I'm from.
I joined on there as an iOS developer and I quickly realized that I was the only designer at this organization. And so I just quickly fell into the defacto product designer role there, which quickly had me working across web mobile, all of the different services. And I quickly learned that we're developing all these applications and designing all these applications for all these different agencies, and they all look to sync. They're all built differently, they all are designed differently, let's share some things here. And that's what really opened up my world to design systems. There are people out here doing this thing where they're focusing on how to increase efficiency and collaboration within organizations. And I really love that.
So at that point, I started moving more towards web stuff. I graduated college, I joined Sprout Social, moved to Chicago and I joined there as a design developer, which was this hybrid role. After a couple of years there, I was able to help found the design systems team. They didn't have a design systems team when I started, we were able to establish that and I went on to lead that team for several years and we created and worked on Seeds, a design system, which has been my baby for the past several years. You can check it out at seeds.sproutsocial.com, but that was really where I cut my teeth on what it actually meant to do design systems as a practice, not just as an interest. And so that was really exciting, learned a lot there in that role, we were a very small team and so I was serving as lead designer and also I was the only front end engineer on our design systems team. So I was doing all of that as well, which was very cool. And then at the end of last year, I made the transition and switched to Stripe. So I'm now at Stripe working on the product design system team there, so focused on the design system that powers all of Stripe’s web products, which is really exciting. Stripe’s a really cool company.
Luke: That's very cool. So, I came across your writing about design systems because of the stuff that you did back on Seeds. And especially around measurement, the way that you folks measured design systems, which is what I originally wanted to talk to you about on the podcast, but then you have to just blow the entire thing up and post this amazing article about the future of design systems, especially the documentation as knowledge graphs, which I'd love to talk about today. Do you just want to give us a whistle-stop tour of what you mean by documentation as a knowledge graph?
Chase: Yeah. I can do my best, the article’s on my site and I've been thinking about this for a long time. And I think the article that I wrote is really more of an overview than a deep dive. I think you could probably write a novel on the intersection of these things. But the idea I think generally is that we tend to document design systems in a very traditional way, the way that documentation has always been done on the web and the way that the web works, which is sort of this collection of the linear isolated documents that are linked together with one way, single direction links.
And I think there's a couple of things that inspired this idea for me. One is the history of the web and the history of the internet, which is something that I'm super passionate about. It goes back to the creation of the web and the original vision of a hypertext system that was maybe a little bit more fully-featured than the web that we ended up getting. Ted Nelson back in the day, had a lot of really cool ideas around, what the web could be featuring bi-directional links and transclusion of documents across the web, which is really exciting.
And in the past few years there's been a lot of consumer tools that have popped up around making these hyper-tech systems accessible to all. Roam Research is a really good example of that obsidian. There's lots of these tools popping up where they're building on that original vision of the web. And what that means is content that is addressable in the smallest possible format, like in Roam Research, individual blocks of texts have unique addresses and they can be embedded and transcluded and linked to. Bi-directional links is a big part of that, if I link to one thing, that thing should know that the other thing is linking to it and allow you to traverse back and forth within that graph.
There are lots of other ideas within there as well, but I think, what's really exciting to me about this with design systems, is that when you scale a design system up, it becomes a real challenge to maintain lots of things. One thing that we ran into with Seeds a lot is we would change some pattern in our design system and we would go update the docs, but then we realized, oh wait, we mentioned this in 50 other places throughout our docs. We have no way of knowing where all of those places are, they're just HTML links right now. There's no system around that. I think, having content that can be shared across many different services means that updating that content can be done in one place. It can trickle throughout your entire system. And I think there's lots of exciting parts to that, to scaling a system. You get to thinking about when you have content that is in those small chunks, you can start presenting those in really interesting ways. You could imagine taking bits of those and showing them to users when they need it contextually, just the bit of information that they need. I think it's something I've always struggled with design system documentation is that lots of it is just really lengthy documents.
I'm trying to design an experience, I don't want to sit down and read a novel. And so I think it's really important that we give people just the information that they need to get their job done at the right time. And we don't ask them to be experts in the system, because not everyone at your company can be an expert in your design system. That's what your design systems team is for. Your users are just that, they're users of that system and we need to treat them like we would the users of a product. We don't expect the users of Stripe to read a Stripe manual before they dig in. We expect our product to work intuitively and so I think design systems should be treated the same way.
Luke: That's like a thread that seems to come through with any kind of design systems, as well as design ops process optimization tooling, right? It's like, we just need to be treating these things as if they're products themselves and actually consider these people as users, as the way that we would treat our users. I think one of the things that really excites me about this concept is the ability to actually have the information that you're presenting be more contextual, which is what you were saying. It's like give them the amount of information that they need when they need it. But also the concept of having a documentation system for the design system that learns with your user, because as soon as you have at a really simple level, I know Notion have put this in place with synced blocks. They’re the first ones that I've seen doing it in like a commercial product
Chase: Yeah. That's a really good example.
Luke: As soon as you have that synced block, you've got all the data behind it, of where those synced blocks then all live. You can start building up really amazing relational models that can second guess what they might need next, which becomes really powerful and it's exactly what you said, nobody wants to read a bloody novel.
Chase: Right. And I think something that's really challenging with design system documentation is a lot of times we optimize for, I want the user to be able to find the thing that they're looking for as quickly as they can and get that answer and leave. But we don't optimize it all for, I want the user to explore this system and learn from it and discover new things. And so I think, that's something else that a knowledge graph can really help out with. If you have bi-directional links, if you have content that's all linked together, you might start reading and go look for something and realize, this is actually related to all of these other concepts. And I can see those relations encoded in this knowledge graph. And I can traverse that graph and I can say, oh, this is how we do icons and buttons. Oh, by the way, you should probably go check out the icon page and learn more about the base icon documentation or just as an example. But, I think that's really powerful. It helps form connections where there might not be connections otherwise in our user’s mental models.
Luke:I think that's the thing as well. If you're treating it like that, you're almost treating it as the design system as well. You’re breaking it down to its smallest elements.
Chase:Yeah, for so many of our users, our design system is our documentation. And I think as a design systems practitioner, for me, it's really important to note that the documentation isn't the system, right? it is just an artefact of the system, but I do think it is a very important artefact and it's sort of the flagship artefact of your design system and it's how a lot of your users will interact with your system exclusively. And so I think it's worth putting a lot of effort.
Luke: Yeah. Basically just thinking about this gets me really excited. Cause I was just thinking as well, even the concept of, again, having that data of where stuff's used is actually, really useful for the design system team as well, to understand where the gaps are and basically it's new data for them to look at.
Chase: Yes. Yeah. And metadata as well, going back to some of the things that we did at Sprout around measuring the system is, we tried to establish some of these ideas in Seeds. This idea of a design system documentation as a knowledge graph is not something that's being fully realized anywhere that I know of. There are lots of systems that are getting at this and pieces that are providing ways to transclude design tokens and their documentation or bits of information. We tried to do some of these things that at Sprout, one thing that we did was set up, we tried to collect a lot of metadata around concepts in our design system. So every page in our system had a scorecard that would tell you when this thing was added to the system, When it was last modified, what state it was in, whether it was healthy or whether it was weathering or whether it was dead and needed to be replaced. And then it would also show you all of the issues that we had collected from our users about this content.
Like any questions that have been raised, bugs that have been filed, all that was visible for every page in one place. And that was great for our users because they're able to see a list of things and say, oh, if I want to contribute, here's a list of things that needs doing here. But it was also great for us, right? We could set up a page and say, Hey, what's the page in our system that has been updated in the longest amount of time and let's start there. And that becomes a backlog for us. Every month let's try to refresh the oldest page in our system or something like that.
Luke: Yeah. that does make a lot of sense. So you've been thinking about this a lot and you were saying that not even the systems that you've worked on, I'm guessing, are you sort of moving towards this at Stripe or is it still too early days to really put?
Chase: That’s a really good question. Definitely thinking about it and we are right now, our documentation at Stripe for our design systems is built on Storybook. And I think that's served us well for a long time. I think we are growing to this state where we probably need to start building out something custom.
And I think we'll probably do that in the next year or so. I would love to from scratch, think about how we might integrate some of these concepts. I think a lot of the challenge though, is that some of these things are really, really hard to build. And I think that's why it's taken so long for us to see companies like Roam and Notion and Obsidian pop-up, it's really tricky stuff, especially when you fold in we want to make sure that there's still a good authoring experience here, right? we don't want to make writing documentation of pain in the ass. We want to make sure that contribution is easy and all these things. And so, with Seeds, our design system documentation we use MDX. All of our pages were Markdown with React components embedded within. This is great, you can store it in Git, it's really easy to contribute anybody can write into it if they write in Markdown. But you don't get any of those layers on top of two-way links or, with Roam, when you're writing a page and you want to include a link to another page, you get an autocomplete list of all the blocks you can include. And that's really key if you want to reference other objects. You can't be expected to memorize the ID of every block of texts in your system. You need some sort of tool that can help you make those links and those tools just don't exist generically right now and I think a lot of this has to do with the fact that we're building on the web and this is not how the web works.
So we have to build those abstractions ourselves and so, Roam was doing that. There are certainly things like this starting to pop up, you start to see Gatsby themes that people are making that replicate the UI of Roam, you can hover over links and get a preview of that page and cool things like that, I think it's a matter of how do we solve this challenge and build this thing without this becoming our full-time job. And without us having to architect a tool that is on the order of magnitude of a product, like Roam that's really hard.
And so I think it's about thinking, where can we start small? And so with Seeds, one of the ways we did that was all throughout our documentation, we're referring to design tokens, we're referring to individual colour values. We're referring to type scales. Let's make a component that we can use in those situations where we can refer to that concept agnostically. And in that can be referenced and updated in one place. And so, in Seeds, whenever a colour is referenced, you can hover over that colour and see its value and that's tied into our design token system. So if we ever change the underlying value of that colour we don't have to update our documentation. It's automatic all the way through. So that's one way that we started building towards that. But we want to scale that up for sure. We want to apply that to you to any concept in our system.
Luke: Yeah. I think that will be the key. And to be honest, I think you're just giving me ideas to take back to Zeroheight to get them to build. But it's similar to us, we've got that at the very base level, but any kind of sophisticated level it's just not there because I actually think that part of the problem is that the mental model is not there for a lot of people. As you said, the web isn't built this way, It's not something the way that people think about it. I suppose the only thing that I can potentially see is an issue, and I'm wondering if you've thought about it at all is, what we're talking about here is unstructured documentation, that then is compiled in a way after the fact, or making structured documentation, but making it so each individual part is, I don't know, that to me is amazing and empowering, but also slightly terrifying if you don't have that process and structure, I'm just curious if you've sort of thought that?
Chase:Yeah. That's a good question. I mean, it definitely is a concern. I think, building this decentralized network of knowledge is very cool, but how do you maintain that? How do you make that? How do you expose that to users? I think in many senses, even if a system is constructed this way under the hood I think in a lot of ways, the way you're going to present it to a user is still probably in a linear format the page of documentation, but I think there are other options as well. You could imagine, and actually, Polaris, Shopify, Polaris does this pretty well. They have a graph QL API for their design system. So you can query and get design token values, but also individual examples of components, it's the data that powers their documentation website. And so their documentation website is very traditional, it's a linear collection of pages of linear content, but there is a graph of information powering this. And I think, finding ways to expose that to users would be really cool. What if you could chat with your design system and query that graph using natural language or something like that. What if you could service it in your code editor and give people hints and tips in the smallest possible sort of chunk. Something we've talked a lot about at Stripe is I've been tinkering with Github Co-pilot and what if we could teach Co-pilot or train Co-pilot on our design system documentation what could happen if we did that?
Luke: See, I'm interested in that. I've been thinking and talking to the engineers at Zeroheight about this a lot as well on the design tool side. It's like, how do we get to a way where we can ostensibly turn our documentation into an API that knows where it's being referenced in the design tool so that we can throw up the documentation, the examples, whilst the user's actually designing. Cause I mean, that's the thing when it comes down to it, documentation is only, as we were saying before, it's most useful when it is contextual to what you're doing at that moment. If you're having to get out of whatever tool you're using to go and reference something, that's not as helpful as it could be.
Chase: Absolutely. Especially if the thing you're referencing is a 5,000 longword webpage, it just becomes overwhelming. When I'm trying to figure out what colour to use for a button, I don't want to have to read the history of buttons and every button permutation that exists at our company.
Luke: Hey, don't forget the 30 sessions of user testing that you did as well to make sure the button was right
Chase: Exactly. And that's another really good point too. Once you find ways of breaking this information up and making it navigable, you can include a lot more information than maybe you normally would. We have this graph and we're not making users read every bit of information to find what they need, we can start including every research session that has been done on this thing at this company. And it's there if you want it and you can find it, but it's not in your way. What a long-term vision for this really becomes is that, I've always thought of design systems and design systems teams as being the anthropologist of design at their company, they're the scribes, they sit and watch and listen to how design is happening and they document it.
And there's an oral history that gets passed down of, here's how this decision was made and this project failed and here's why we didn't do this. And all of that needs to be captured. I don't think it's really easy to do that now, but I could really see this growing to become a history of how we have always done this thing at this company and how it's changed over time. When you start getting to that point, you start solving the problem of repetitive work. A new designer comes into the company and wants to design this thing and they don't realize that, Hey, we tried that three years ago and that didn't work and we didn't do it for XYZ reason. We can provide all that information. I do think at that point, the design system documentation starts to become mixed with the documentation for your organization and your design org and that makes a lot of sense. I think documenting a design system should be more like documenting an organization than maybe a product if that makes sense. And so I think there's a lot of interesting parallels there.
Luke: Yeah, it's one of those things, I was talking last season to Amy Hupe whose a content strategist.
Chase: I love Amy. She is one of my favourite people in design systems. Shout-out Amy.
Luke:I do think that if anybody doesn't follow Amy they need to rectify that right now. But it is one of those things where having talked to her about this it's alarming the amount of design systems — big design system teams — that don't have anybody who has any background in content or content management or information architecture, or basically knowledge management.
Chase: I think that's a big part of it. You start to see companies nowadays hiring Notion experts. They're essentially hiring librarians and knowledge management experts, just to manage the knowledge base that is their company. And I think that is absolutely applicable to design systems as well at a certain scale. You need someone thinking full-time around, how was our design system structure organized and how are people ingesting the content that we're providing.
Luke: One hundred percent. Okay, so, I'm curious actually. Have you seen any great examples out there? Well, I suppose you've mentioned a few, so you mentioned that Polaris, and you've mentioned obviously that the stuff that Roam are doing, but any particular design system documentation sites that have just completely blown your socks off.
Chase: That's a good question. Maybe, because I'm holding myself to a bit of a standard here. I don't know if my socks are easily blown off. Not because people aren't doing great work out there, but just because I have such high hopes for what this could be. The one that does come to mind is, the Orbit design system, which I think is called Kiwi, I believe, they're doing this in a lot of ways. They're doing some of the things that we did in Seeds, the token tags let you see contextual information. They're also pulling in some other features that I think are really exciting that are taking inspiration from the web and hypertext. If you go to their design system you can bookmark individual pages and those that live with you. And so you can create your own collection of your most visited content and it changes and grows with you. I'm sure they're doing lots of other really interesting things there. That's something that I think is really exciting too, is customization and personalization of a design system. With seeds, something that we were planning on working our way towards, we didn't quite get there was, can we change the way our design system documentation looks and works based on your role.
So it can know if you're a designer or a developer and change the way things work for you? I think Orbit does do this. I think they have a toggle on the bottom of their site that's like, I'm a developer. And if you toggle that on you go to the code tab automatically when you go to a page, that's a really small example of that, but I think that there's some really exciting things there that you could do as well, which is that once you have this knowledge graph, you can get context about who's browsing the graph and you could change things up about the paths that they take through that graph.
Luke: Yeah, you could actually use user's data for good as opposed to what most companies are doing. That is one of the most exciting areas that we can get into and I will say because you are too humble, I think everybody does need to go out and check out Seeds because, it is one of the best, it's one of my standard examples of what a design system documentation site should be.
Chase: Thank you very much, we put a lot of effort into that. So it's something that was really important for us at Seeds. We had such a small team that contribution was huge. Almost all of the content in Seeds didn't come directly from our team. It came from, we may have written the documentation and designed the layout of the page, but somebody else designed that experience, we put a lot of work with Seeds into making sure that our documentation was really easy to contribute to, really easy to spin up a new page and create something really rich and interactive. We debated a lot, should we use a CMS? Should we hand-code these docs? That was a question CMS, obviously, it makes it really easy for folks to contribute, but we really wanted to create something that was more handcrafted, more interactive, really rich, less images, more live code examples, more bespoke layouts. And whatever's right for this page should be the way that that page is designed.
Luke: I'm actually curious because it's one of the things you assume with impressive design systems and design systems documentation sites, and just generally, that the teams are huge. And I know now from having talked to a lot of people, this isn't the case. So just so that we can start to get this idea out there that you don't need a team of 50 people. How big was the Sprout design system team?
Chase: Three at max — three people at its biggest. Three for a long time and then for quite a while, it was just two of us for a lot of Seeds’ history. Now that's to say, it was two of us working on the core team and lots of collaborators and contributors. We had a working group ambassador set up throughout the organization who were helping us, but yeah, there's just the two core collaborators, essentially me and another product designer, which is not very sustainable, I will say that it's amazing to see what a small group of people can do, but also, you have to realize that those two people are probably working their asses off and maybe killing themselves to do it. So I think there's something to be said about not glorifying small teams doing a lot of work because the much better situation would have been hiring a full team, but yeah, we were able to do a lot and I think, it was really a great way to cut my teeth on design systems and figure out how can we do this really scrappy and get to a point that we're really proud of without working harder
Luke: Yeah, that's it. I'm definitely not for, hustle, hustle, hustle culture, because that is bullshit.
Okay. So I think it's about time that we're going to send you off to your desert island. We’re going to set you off in the boat and you get to take with you, for your indeterminately long stay. One piece of music, one piece of literature and one luxury item. So. What are those for you? First off, let's start with the music. It's always a good place to start.
Chase: I spent a lot of time thinking about this, I have music going basically 24/7. If I'm not in a meeting I have music playing. So it's really hard for me. I have to go with Frank Ocean's Blonde though, that would definitely be, if I have to pick one album of anything, I think that one could sustain me for the longest on a desert island. It was hard even to pick between Frank's albums, to be honest with you, but, yeah, I'm going to go with Blonde that one sticks with me.
Luke: I mean, it matches the vibe of the island too. So that's quite good. As long as it’s not an island in the Antarctic ocean or anything, I'm assuming it's a good island.
Chase: I'm hoping to get a tropical warm breezy island.
Luke: Definitely. And how about the literature, a book? Are you taking the collected tweets of Kanye West?
Chase: Yeah, this was a hard one. I mean, I'm not too picky about books. I read a lot. I like to read a lot of different genres. I even started thinking about blog posts that I would take if I had to really dig into it, I think there's probably some blog posts that I'd print out and take with me. As far as books go, I really loved this book called Broadband by Claire Evans and it's, I'm a sucker for anything that tells the history and the beginnings of the web and the people behind it and what it all could have been had it not gone so horribly wrong and we hadn’t entered the darkest timeline. And Broadband's a really great book about the history of computing told through the lens of the women who made it possible and are often not acknowledged. And it's a wonderful book for that reason, but it's also just wonderfully written and very exciting. And you'll learn a lot of stuff about the web that you never knew. So highly recommend that book for anyone.
Luke: I'm adding it to my reading list right now. How about your luxury item?
Chase: This one is maybe a boring answer, but I would say an iPod loaded with all of my music I don't know, like a solar-powered MP3 player or something, some way for me to listen to music. That’s how important music is to my life, that would be my number one thing. If I was getting shipped off to a desert island I would think, how in the hell am I going to listen to tunes? And a classic iPod loaded with all of my favourite music
Luke: One with the original click wheel, right?
Chase: Only if it has the click wheel!
Luke: Yeah, of course, amazing. Well, we'll leave you with your iPod, some Frank, some Claire Evans and bid you farewell and wish you a comfortable stay on the island.
Chase: Thank you very much. Really appreciate chatting with you. This was really fun.