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