That's my JAMstack
Bryan Robinson
Podcast
Episodes
Listen, download, subscribe
Kathleen McMahon on writing docs, helping others learn and design systems
Quick show notes Our Guest: Kathleen McMahon Her JAMstack Jams: MDX | Gatsby Special thanks to Kathleen for doing the transcription for this episode Transciption Bryan Robinson 0:03 Welcome to another jam packed JAMstack adventure on That's My JAMstack — the podcast where we ask the fantastical question, what is your jam in the JAMstack? I'm your host, Bryan Robinson. And on today's episode, we had the amazing Kathleen McMahon. Kathleen is a developer and design systems guru and I had an amazing conversation with her. But before we dive into the interview, I do want to mention that our amazing sponsor TakeShape is back again this week. Stick around after the episode to hear more about their amazing content platform for the JAMstack, or head on over to takeshape.io/thatsmyjamstack for more information. Bryan Robinson 0:39 All right, Kathleen. Well, thanks for joining us today on the podcast. Kathleen McMahon 0:41 Thanks for having me. Bryan Robinson 0:42 Cool. So let's, let's talk a little bit about you. Tell us a little bit about yourself. What do you do for work? What do you do for fun, that sort of thing. Kathleen McMahon 0:47 Okay, so alright, let's break this down. For work, I am the Tech Lead for the O'Reilly Media Design System. So that's an internal open source project. We're trying to get you know, just a consistent look and feel for our components and our just our materials. I don't know if you've ever heard of design system, kind of a hot topic lately, but yes. Bryan Robinson 1:10 A little bit. Kathleen McMahon 1:11 So that's what I work on. For fun, in the fall mostly, I race cyclocross — very badly — on a single speed in the back of the pack, because everyone laps me twice, and I wear costume to make everyone that passes me laugh. And I also put tunes in my back pocket. So we have, you know, soundtrack, we have costumes. Everyone knows me because it's a person who wears, you know, like this... it looks like this lit up thing of like — spaghetti — with like a Spam costume backwards or an M&Ms costume backwards, you can be entertained! Bryan Robinson 1:51 Have you ever caused any wrecks with that? Like have people like laughed so hard, they fall off? Okay. All right, good. Good. Bryan Robinson 1:56 No, no, no, I've been doing this for a very long time. Like my, I'm much better at soccer, but I love to I love and I love soccer, but I love to bike. I'm just horrible at it. And it's fine. I just like to be at the back while everyone else is racing like going hard. And I'm back there just chilling out. Bryan Robinson 2:14 Nice and you get out you get outside, you have some fun, and you have let other people have fun while they're competing, too. Bryan Robinson 2:19 Yeah, exactly it's this huge camaraderie. And you know, who's coming, everyone announces they're coming and just you hold your line and someone else passes you and, you know, you making sure you're not holding back the leader. Everything's good. Bryan Robinson 2:34 Well, very cool. So... so let's talk a little bit about the JAMstack. So what was your entry point into this idea, either JAMstack or static sites or wherever you kind of started with it? Kathleen McMahon 2:42 Ah, that's a very good question. So, um, how I got into JAMstack was... so our design system has documentation. And our documentation site was built before MDX came out. So before JAMstack was really a thing. So it was around 2018 when MDX spec was really starting to get, you know, baked in a bit. And the way we were generating our documentation site is we had a separate repo. In that repo, we were using react-docgen, to generate our, our component. Kathleen McMahon 3:24 For example, our component pages. So we could use Markdown and it was awesome, but we had to use it in a very brittle way. We had to, we had a script to scan through our component files to you know, create, you know, data for props, tables, spit that into an object. We would have. We would use our Markdown files to write down like, you know, this is your primary button. This is the code for it. This is how you should use it. But we had to write our Markdown in a very specific order. We had to have like an h1 for our, our component name. We could have one paragraph — but only one paragraph — of intro paragraph. When we had two, you know, you could write it, but only the first one would show up from our script. And then we would have, you know, every single variant had to be written as an h2 with, you know, the variant, but not to be... only one paragraph, only one variant, and you couldn't put any h3s in there, you couldn't do anything else. And the minute you started, being freer with your Markdown, things would not render. And you couldn't even bring in rack rack, I'm sorry, you couldn't even bring in React components at all into the Markdown. So you were... you would have this one file for the information that was in your Markdown, and you'd have another file that would grab everything from your React components. Put it into a different object, and you would cobble them together in this very just... it was so hard to work with that... Kathleen McMahon 5:05 Even as someone who was used to the code base, it was hard. And for people that were contributing, they would flee. I just did a talk about this in early February for Gatsby days. I was talking about this whole journey and it was just I use a lot of penguin gifs. Penguins, you know, fleeing and running away and just like, you know, just hitting their head against the glacier because everything was brittle. So this is why once the MDX spec matured, I was like, "wow! We could do some more, so much more now. We can write what we want to write. What we write will show up on the page." And this is so much more exciting to use. And now we can have contributors that want to come in and say, "Oh, you know, I found a typo." Just you know, fix the typo, push up a commit. Bryan Robinson 5:42 And don't worry about the actual structure of your markdown. You're good to go. Bryan Robinson 5:45 Right. You're good. Yeah. Bryan Robinson 5:47 So, so that's MDX and obviously, Are y'all using Gatsby then for the design system documentation? Bryan Robinson 5:54 Yes. Bryan Robinson 5:54 Very nice. Kathleen McMahon 5:55 Yeah. Bryan Robinson 5:56 Kind of walk through that a little bit for me. Bryan Robinson 5:59 Um... Do you want to me to walk you through my learning curve? Or...? Bryan Robinson 6:04 Well just kind of like I guess transitioning from the React docs to Gatsby. Bryan Robinson 6:09 Okay, so that was a two weeks of pain that was so worth — it was so worth it. Um so what I did the transition was I... went to Gatsby. Of course my cat is meowing right now. That is Thor if you ever hear him meowing. That is Thor, the Mighty Thor. What we, what I did was... I went into the Gatsby site, I did their tutorials. I went to tutorials one through eight and um, you know, made myself a site. And after following that, tried to figure out what was missing because that — you know, that the tu- tutorial, you know, walks you through, this is how you get started, you know, doing a blog post and all these other things. And it started with with some Markdown. But it was missing some stuff. So you had to like write down what what everything, you know, everything that you missed. And I would get stuck on certain things like either creating pages, or the GraphQL query. Because you had that, you had to figure out like where, where you had to modify either the Gatsby node page, or the Gatsby browser page, or the Gatsby config. And you had to do it in a certain way. So, once I found out the right combination of understanding that I had to adjust my config, so it would support like post — because we just use postCSS in our projects. How to use themes because I watched a Twitch livestream stream with Jason Lengstorf and Chris Biscardi, and they were talking about the experimental themes. So I followed, you know, what they were doing and made a theme within a theme while it was still experimental phase. Grabbed that into our doc site, tried to make things work, and the hardest part was trying to — it wasn't where you would make your, you know, your source pages and, you know, just generate your files — it was talking to the separate directory where our components were because... We wanted our components, we wanted a better separation of concerns of documentation for just a general doc for general docs, one location. And not in a separate repo anymore. In, it's just this separate directory in this one repo. But our, our components are hosted in a source repo. And so we have it for better separation concerns we have, you know, the button component is in a folder with all you know, all its files. And so you can always keep everything you know, all you know test files and CSS files and you know, Storybook file, and the Markdown file all co-located in, you know, one location. So make, you know, make maintenance easier. Now, with that the hardest part was trying to figure out, "okay, how does Gatsby talk to this source folder?" And once you found the right combination of, you have to do a query this way, and you have to point it to the right you know you have to use these plugins like the Gatsby... Gatsby file, plugin and you add/use, you know, this other plugin which I could pull up the code base to to remind you of all the words right now, but I can't because MDX right now it's on my brain, and I'm very excited about it. But! I'm figuring out and looking at it right now. Ahh. There we go. So with with the config, you know, you have things like the page creator, the file system, you had to learn, you know, how to resolve your paths. And if you were, if you were new to you know how to use Node at all, it's a learning curve for anyone. Or if you haven't done Node, for
That's my JAMstack RSS Feed
