Ep. #72, Documentation Deep Dive with Megan Sullivan of Gatsby
about the episode
about the guests
Brian Douglas: Welcome to another installment of JAMstack Radio.
On the line, we've got Megan. Megan, what's up?
Megan Sullivan: Hello. Not much. Hanging in there, it's COVID times.
Brian: And I was totally looking for the Zoom window to see your last name because I scrolled down far enough to not see your last name.
So Megan Sullivan, for anybody who is wondering who Megan is.
But anyway, Megan, who are you and what do you do?
Megan: Yeah. So my name is Megan Sullivan and I am a senior software developer at Gatsby right now.
I'm specifically focused on documentation, that's part of my title.
Before that, I was a software developer consultant at a company called ThoughtWorks and before that, I was an educator.
So working mostly in CS education, doing curriculum development and writing learning things.
Brian: Was that at a grade school level, high school level? What level of education?
Megan: A little bit of both.
When I started out, I was doing an AmeriCorps program called City Year.
So I was working in a third-grade classroom doing in-classroom support and teaching them to code was sort of something I did for fun on our lunch breaks.
I would just bring a couple of them upstairs and they would play coding games on my iPad and we would talk about variables and loops and things.
And then after that AmeriCorps program was over, then I interned at Code.org and they do K through 12 curriculum.
So I was working more on high school age stuff.
And then after that, I went to work at a nonprofit called Girls Who Code and they focus mostly on middle and high school girls.
But they also have some books for little kids too, they kind of are doing the whole age range.
So I've got a little bit of experience in a lot of different age groups.
Brian: Wow. Yeah. I mean you mentioned AmeriCorps, you literally took a tour through all these different education things.
So and then I'm sure everybody's wondering did you teach Obama how to code too as well?
Megan: Oh, no. God, that would be amazing.
I was not one of those people, although he did do, I think that there's a video somewhere of him doing the Hour of Code curriculum, which was the same curriculum that I was using to teach my third graders.
So they've done stuff Obama's done.
Brian: I listened to an interview of the person, I guess, who started Code.org or someone who was in the early days had an experience of getting Obama to do the Hour of Code, which is how I remember the reference.
But in the picture, they had a laptop and they had to cover up the Apple logo so they put the Code.org sticker on it.
Because it wasn't actually Code.org branded that event.
It was the Hour of Code brand that they were sort of talking about and then now everybody associated that event with that because the sticker on the laptop.
Megan: Oh, nice.
Brian: But I forgot what podcast I was listening to about that and we are going off the rails and sort of hearing your story too as well.
But I wanted to get into what you do at Gatsby but before, I wanted to pick more of your story out and try to figure out, you talk code to the CS realm.
But I'm curious, did you get a CS degree or did you specifically go to school to learn how to do that?
Megan: Yeah, I did. I had never really coded before college.
I had a Myspace, I'm dating myself but I had a Myspace and I learned how to customize my Myspace profile via a, I think it was a Neopets HTML tutorial that they had online.
So, a lot of pop culture references.
Brian: Yeah. All of them that I get so you might be dating me as well.
Megan: There we go. See, so we're in the same demographic.
So I had never built a full program on my own until college.
But then when I was in college, college curriculum, they're not always super engaging.
It's kind of dry.
I was learning how to do stuff but I was really struggling with the content because it wasn't taught in a way that was super relatable. But also with just sort of identifying as a developer because all of my professors were old men. And I didn't really see anybody who looked like me or who was even doing stuff that I was really interested in.
So by the time that I graduated from college, I was really just feeling like this isn't for me. I don't want to be a code monkey.
I remember that phrase being in my brain.
I don't want to just be somebody who sits in a room and codes in the dark and doesn't ever do anything meaningful.
Brian: For context, you are in a room.
Megan: Yes, I am in a room.
Brian: But the light is on though.
Megan: That's true. That's true. I don't have a hoodie on.
And so then teaching third-graders how to code and seeing how excited that they got made programming be something that was fun. It was the first time that I had seen them really get excited about loops.
And one of the things that we added into the curriculum when I was at Girls Who Code, we wanted to try and highlight role models who were doing cool things with technology to improve their communities and have an impact on the world.
And so we wrote a lot of these women in tech spotlights to showcase those kinds of cool projects that people were building.
And in the process of researching those and seeing all of the different applications and industries and just things that you could do with tech.
It really inspired me to be like, oh, you don't just have to work at a FANG company.
You can do something that's more on the ground, has a more direct effect on people's lives.
Brian: OK. Excellent.
And I'm curious to see if that excitement sort of transcended into what you're doing today working with docs.
You had mentioned that you're a senior software engineer but your primary focus is the docs.
So can you talk about what part of Gatsby do you touch and how that sort of encompasses in that title?
Megan: Yeah, totally. So there's kind of two main things that I focus on.
One is reviewing documentation, pull requests.
So our internal engineers, they'll be working on a new feature and it'll be ready to go out into the world.
But we need to tell people what it is and why they care about it and how do they use it.
And so I'll help review those kinds of things for kind of the structure of the documents and also just, are we including enough context so that somebody who's new to this feature understands what the use cases and why it's cool.
And then there's also this sort of bigger picture piece of the docs as a whole, like what do we want our docs experience to look like overall.
So within the last couple of months, we recently launched a new reorganized version of our docs site.
So it's a pretty big overhaul from the last version.
Because we just got to this point where we realized we have all of this documentation that has grown really organically as we've gotten more contributions from the community and added new features.
But our site had gotten to this point where it was a little bit unruly, there were lots of nested levels of docs and it was hard to find things and there were things that were redundant.
So one of my first big projects, when I started, was figuring out how do we reorganize all of our content basically so that it's easy to find things. And also just so that you have a better mental picture when you're looking at the docs, like what's in here and where might I find what I'm looking for.
Brian: OK. Excellent.
And it sounds like you all shipped that in November, it's already out live, people can see this?
Megan: Yes. I think it was December, it was right before the holiday break.
It was a little bit like, OK, we're sending it out into the world and I hope that it works because I'm going on vacation.
Brian: Excellent. Yeah, that's awesome. Yeah.
And I was just looking at the, I'm looking at Gatsby stocks now and I love their approach to UI and how clean everything looks.
I'm kind of loving the UI in general.
Megan: Yeah. Our designer Flo did a great job on those docs. They're beautiful.
It was like, I sent him a prototype that was really just a Google doc with some boxes on it and he turned it into this beautiful UI and I was just like, wow, that was amazing.
And he does it so quickly. He's great. Shout out to Flo.
Brian: Yeah, shout out to designers just in general.
I'm curious though, I had mentioned this in our show notes, the last time Gatsby was on--
This is the third time Gatsby is actually had an episode on this podcast.
So we had Kyle on first, early days on JAMstack Radio.
And then we had Jason on last a couple of years ago and then now you're here so to sort of rounding our third.
But I'm curious of what has changed in the last six months just Gatsby as a whole?
So we have new docs but just curious about there's any new changes that we could be on the lookout for?
Megan: Yeah, totally. There's a lot of exciting, fun things.
I can only talk about some of them, some things are very exciting but we're saving them to announce at GatsbyConf, which I guess I'll plug, is coming up on March 2nd and 3rd.
So it's totally remote, it's free.
You can come and find out about all the fun things that people are building because the engineers will be able to talk in more detail about the specifics.
But two things that I can sort of tease for you now that actually are available already.
You can start using them if you update to the latest version of Gatsby, there's the file system routes API.
So in the past, if you wanted to programmatically build pages, you had to have a Gatsby node file and you'd have to use the create pages API and do a bunch of work yourself to generate pages.
Let's say that you had a bunch of markdown files for your blog and you wanted to create a new page for each blog, you'd have to write the code to generate those pages yourself.
But now with this file system route API, you can just use the name of your file and it will do all of that for you.
So if you want to pull out all of your MDX posts by the slug, by whatever the URL path would be.
Then you can just name your file source/pages/ you use the curly brackets and then put MDX.slug in the middle.
And it will automatically, it'll generate the GraphQL query for you, pull all of those nodes, build all the pages itself.
And then you can just focus on like, OK, within that page template, now what do I want the contents to look like.
So it makes your life a little bit easier.
And there's also, you can do client-only routes with a similar syntax.
So if you wanted to have pages that you can't build at build time because if it's user authentication or something like that, you can also use the routes API for that too.
Brian: And I understand Gatsby from my understanding I've been using it a lot for just statically generated stuff.
So I do a lot of stuff at build time, I've never done anything with authentication.
So would you connect that to and I guess serverless function or does GatsbyCloud handle that for you?
Megan: I don't actually know because I myself have also only used it for static stuff.
So that's one of the fun things about being at Gatsby.
Now I get to try out things that I wouldn't do on my own for my own personal website.
So I haven't gotten too into that yet but the way that I understand it, there's more use cases for things like authentication or things like e-commerce if you're doing stuff with that.
But yeah, they'll know more details at GatsbyConf I'm sure.
Brian: Yeah, yeah. And I know this because we actually met quite a few months ago actually, so you've been at Gatsby for six months at this point?
Megan: I started in September. So what is this? Maybe five months.
Megan: So I've learned a lot since then but there's still a lot to learn.
Brian: Yeah. But your use cases, has it always been around the docs ecosystem?
Because I know Gatsby, when I talked about Gatsby internally to my docs team at GitHub, there's a lot of excitement around Gatsby.
Because we're leveraging a lot of those tools internally at GitHub.
I don't know how much of that stuff is public and how much of that we talk about.
But I would say the docs community, they always tend to have excitement when it comes to managing statically generated pages for documentation.
So is that where your background came from really with Gatsby?
Megan: Yeah. Well, my background before I started working here I really had only ever used it for my personal blog.
Megan: That was all the experience that I had.
So it was really just, wrote some markdown posts and needed to create a blog from that.
So I actually wanted to touch base on, so your introductory to Gatsby and I think we were chatting and you'd mentioned you only use Gatsby prior for your personal blog.
But I'm curious of what other use cases folks can sort of leverage Gatsby for, you mentioned e-commerce.
Megan: Yeah. I know that the team is focusing now on how do we make a better e-commerce experience for people.
So I know that some of our clients, I guess, some of our GatsbyCloud users are big retail e-commerce sites that are trying to figure out how do we move our products here.
How do we pull in data from our CMS?
And I think that's one of the cool things about Gatsby is because there's this GraphQL data layer that's built-in, you can pull in data from anywhere as long as there's a source plugin that handles that integration for you.
And then once the data is in the data layer, you can do whatever you want with it on the front end.
Brian: Yeah. And that's one thing I loved about Gatsby is the plugin ecosystem because things like Contentful, I don't have to figure out how to point wires and cross them to make sure my Contentful data can show up on the page and be nested in my GraphQL queries.
And I chatted with Kyle about this quite a few years ago because Kyle's background is from the Drupal space.
So that sort of approach to having a sort of hosted version versus having your self-hosted version versus using plugins, it's what I love about the JAMstack.
Because a lot of stuff that we do in JAMstack is not new, we're just basically borrowing from other ecosystems and previous encounters.
And I know there's popular conversations between Mat Biilmann and Matt, other guy from a WordPress.
Netlify and WordPress guys.
And sort of like them just basically having conversations in parallel but really at the end of it, they can agree that the technology's been the same.
But I did want to ask because you mentioned it, GatsbyCloud, it's something that I have not really even paid much attention to.
What's that distinction between GatsbyCloud and the open-source version?
Megan: Yeah. So they're sort of two separate entities.
So Gatsby the open-source framework is the framework that you're using to build your websites.
And then GatsbyCloud is--
I'll start this out with a caveat that I'm not one of the salespeople so I won't be able to give the best pitch.
But what I understand at the moment is that GatsbyCloud is our, it's how we help you build Gatsby sites quickly.
So right now you can set up your GitHub repo to connect to GatsbyCloud so that when you push changes to your repo, it'll trigger a new build on GatsbyCloud.
Which then will give you a build URL so that you can preview those changes before you send them wherever it is that you want to host them.
Brian: OK. Excellent.
Well, I appreciate you taking a try at pitching that to us.
I think I kind of understand it, understanding that I kind of hinted at it with this whole WordPress architecture where you have a hosted version.
You could actually get a site up and running really quickly.
I think that's kind of game-changing when it comes to react applications.
Because one of the things I don't like about WordPress, WordPress is a fine ecosystem, its architecture, whatever. I just didn't learn development through it.
So when it comes to someone like my brother or sister, mother, saying, I want you to help me with my WordPress site.
I usually am just kind of like, I don't know where to even begin and not that that's wrong or right.
So if I do have someone that approaches me and has something in GatsbyCloud, I'd know I can at least understand what's going on in their repository.
And that's the one thing I do like about that and other tools as well is that we're sort of, not centralizing but in the JAMstack ecosystem, we're all sort of figuring it out this together.
So we're all just kind of convinced that Git is the way to do source control, which I love because I know how to use Git.
And then all the other things, I just sort of know how to do that so I can move on.
And if I don't want to use Gatsby, I can always use something else but why would I do that?
But speaking of that, I wanted to ask, what are ways for people to get started with Gatsby?
So if you were to start a new site today, what sort of steps would you go to?
Where would you look to sort of get started?
Megan: Yeah. So as of this moment, the best place is probably our tutorial.
If you go to our doc site, it's gatsbyjs.com/docs/tutorial and that walks you through how to create a new site from the ground up.
It starts at, how do you install the dependencies?
How do you get your machine set up to even be ready to start this project?
And then it takes you through how do you build a new site, how do you add components, how do you style it, how do you work with the data layer.
The one thing that I'll add about the tutorial right now is that it's a little bit outdated when it comes to the new Gatsby features.
So it doesn't include the file system routes API yet.
There's also the new Gatsby plugin image it doesn't include.
But that's something that I have on my docket for a few months down the line is starting to work on updating the tutorial so that it has the latest and greatest Gatsby features.
But if you are looking for an intro to those, I am facilitating a workshop at GatsbyConf, it'll be on March 3rd.
Obinna from the developer relations team and I are co-running it and it's called Getting Started with Gatsby.
And so that'll be basically the test run of what we're going to put in the new tutorial, just to show the same things of how to build a site, how to add components.
But using the newest, latest, greatest Gatsby features.
Brian: Yeah, looking forward to that.
And then looking forward to folks who are listening, definitely check out GatsbyConf, and please go to Megan's workshop.
You're going to learn a lot. And excited to, honestly, it's been a while since I updated any of my Gatsby sites, so I'm even out of date today as well.
Megan: Same. So am I.
Brian: So before we move into jam picks, I did want to ask real quick about the gatsby-plugin-image and sort of what that is.
Because I think we sort of passed by it, assuming that everybody knew what you were talking about but did you want to sort of explain that?
Megan: Yeah, totally. So gatsby-plugin-image is a new Gatsby plugin.
It's in beta right now but it's available and ready for people to test out.
And it's the new version of the Gatsby image plugin.
So there's a lot of names that sound very similar but the old one is gatsby-image is the name of the plugin.
And this new one is gatsby-plugin-image.
Brian: Got you.
Megan: And it's been updated so that it's got an API that's a little bit easier to use and understand and it also has better performance.
So a couple of the new things that you'll get if you switch to that plugin, there's a new static image component.
So now you can load images without needing to use GraphQL.
So if you've got your logo always has the same image that's loaded every single time that component is used, you can use this static image component, and then it looks very much like an image tag where you just swap out the source URL.
Megan: And then there's also a couple other things.
There's new layout formats, so when you resize your screen you can get different behaviors.
And then there's also added support for AVIF, which I guess is the new fancy image compression format, something like that.
Brian: I believe you. I haven't kept up to date with all these different formats, but yeah, there's yeah, I thought WebP was the new one but yeah.
Megan: Oh, yeah.
Brian: That is another one too.
Megan: Yep. If you're into compression algorithms and know the difference, let me know.
Brian: Yeah. We should have a-- I'm making a note to myself, I should have Tessa on to talk about Cloudinary because I know she does DevRel over there.
Megan: Oh, cool.
Brian: It's been quite a while since I had Cloudinary on as well.
But we're going to move on and talk about jam picks.
Thanks for the conversation on Gatsby and catching us up with what's happening and even the GatsbyConf coming up.
And also super happy to see that you all were able to ship the new docs and also ship new tutorials in the next couple of months.
We won't give you a date on that but yeah, people will give you time to update that stuff.
Megan: I appreciate it.
Brian: But yeah, talking about jam picks, these are things that we're jamming on.
Things that get you going, good music, food-related, technology-related, all is applicable for this section.
But if you don't mind, I'll go first and talk about my picks. My first pick is Clubhouse.
Now, this is a pick that I just recently got into. Have you heard of Clubhouse, Megan?
Megan: I have. Clubhouse is also in addition to the tool that everybody on Twitter talks about, it's also the name of the tool that Gatsby uses for project management.
So I was very confused at first.
Brian: Oh, really?
Megan: Yeah. But it's our JIRA. So I was just like, "Why is everybody so excited about Clubhouse?"
Turns out there's two of them, two different.
Brian: Yeah, yeah.
This is definitely not about project management, it's more about these sort of hidden club for people to have, I guess podcasts.
It's really weird. So the platform it's audio-only and you create these clubs, these rooms basically and people can join them and you can talk about a subject.
So it's essentially on the surface it sounds really either dumb or bland or more gatekeeping.
But it is what you're making of it. So I actually hosted a Clubhouse last night on GitHub Actions and I didn't know what I was doing.
So I was like, yeah, I'm just going to try this thing out.
And now that I've hosted a Clubhouse because I've only just sort of sat in a room and listened.
Hosting it, it's nice. I was able to sort of set a time in advance.
So you have to set a time in advance so that way you could have a shareable link and then you pick the subject and then people show up.
But then you have to remind people that it's actually starting and it's really weird but you go back to Twitter for that.
It is invite-only at the moment as you know as you do in Silicon Valley with new apps.
So there's a bit of buzz because of that because only people who have access can give access, which is part of the whole gatekeeping thing right now.
I honestly did not know that tech people were sort of in the Clubhouse until the last couple of weeks.
I originally got invited to Clubhouse back in December from one of the people I go to church with.
So I thought it was, frankly, I thought it was a black person thing because everybody I knew on Clubhouse happened to be people I knew in the black community.
And all the rooms I went to were talking about other stuff.
And then when the parlor thing happened or the January 6th insurrection of the Capitol, Clubhouse was, that's where I found my people and we had a conversation.
So then last week people are talking about Clubhouse who are in tech and I was like, oh, I guess this expanded.
But actually, it turned out it's always been for tech people, I just never paid attention to until recently.
So anyway, I saw people were hosting Clubhouses, mainly Nader Dabit who does AWS, he's a DevRel over there.
He hosted a Clubhouse, I was like, oh, I should try this out. So I did it. It was a great experience.
It was almost like having a sort of, at conferences sometimes you have unconference rooms or people can sort of write on the wall and have a talk.
And then be able to sort of this, give them 30 minutes to do the talk or whatever they want to do.
So that was to filling and then I can invite other people. So Nader was actually in my room.
I invited him up to the stage and he was able to unmute and talk and then I can kick back in the regular people's area.
So it was very interesting experience, I don't know if it's going to last very long but if you can get an invite, definitely try it out at least once.
And then I would also say that there's other ways you can have conversations.
I think Twitter is doing something like this as well and Discord has chat and all this other stuff.
But I just really like being connected to the people during this time.
So shout out to Clubhouse, try it out before it goes away.
And then my second pick is going to be Open Source Friday, which is a thing that we met on, which is GitHub hosts these Twitch streams on Fridays.
We're actually starting them back tonight, is the first time. We're doing an Australian version.
When I say tonight, you're listening to this podcast and it could be any time of the day.
But tonight when we're recording this, I'll be doing one later today, I'm going to be teaching my coworker how to build Twitch integrations that talk to GitHub.
Your GitHub repos and kind of it's a tool I built called GitTwitch.
There's a repo bw/gittwitch, so you can definitely check it out.
But essentially you can star a repo or do something on a repo and you get a notification on the screen on Twitch as you're streaming.
So those are my picks. You can check out Megan and I's video on youtube.com/github.
We have a playlist in one of the last ones we did was with Gatsby and Megan.
So that was long-winded. Megan, do you have any picks for us?
Megan: Yeah, so something that I have been really enjoying over the last couple of weeks, Aisha Blake, who I used to work with when she was at Gatsby has a new Twitch stream, or I guess she's revived her Twitch stream, every Thursday at 3:00 PM Eastern.
She talks about tech education and she has different guests on, I was a guest on one episode but I really love hearing people talk about education.
I could listen to people talk about how they teach people things and how they break down complicated ideas forever if the world would let me.
But she's had some really cool guests on and she's lovely and it's a good time.
And I think, especially now that it's COVID times I am getting more into watching streams because it's that sort of organic less structured conversation where you can just feel like you're hanging out and having a good time.
So it's a lot of fun, I would definitely recommend checking it out.
Brian: Yeah. I am a big fan of it. I love it.
So I started doing it a year ago for my personal Twitch and it was really because I do DevRel.
And depending on what team you're on, you don't ship a lot of code that stays around a long time.
So I wanted to build a project that I could just be happy with, I could learn how to do modern-day testing and all these new tools but not sort of slow down my day job.
So I started live-streaming Twitch back in January, not realizing the entire world would just be home.
So I stopped traveling and then I just had all this extra time to do a Twitch stream.
So that's sort of how I got into it and I've enjoyed it because I built kind of a group of friends that show up and hang out with me while I live stream.
And they just show up like clockwork every time I hit live, which is, it's a lot of fun.
Actually, you'll have to give me the link to Aisha's, I don't know if she uses the same Twitch account as her Twitter.
Megan: Yeah. It's twitch.tv/aishacodes.
Brian: OK, perfect. Well, I'll make sure that makes it in the show notes, and thanks for your picks.
Thanks for the conversation about Gatsby.
It was super enlightening and just learning about what's changed but also your role in the docs team and sort of pushing docs forward.
So, I appreciate your time. Listeners, keep spreading the jam.
Content from the Library
The Kubelist Podcast Ep. #31, Kustomize with Katrina Verey of Shopify
In episode 31 of The Kubelist Podcast, Marc and Benjie speak with Katrina Verey, Senior Staff Production Engineer at Shopify....
Jamstack Radio Ep. #115, Reimagining Terminals with Zach Lloyd of Warp
In episode 115 of Jamstack Radio, Brian Douglas chats with Zach Lloyd of Warp. This talk explores tools and practices for making...