Library Podcasts

Ep. #27, API Documentation with ReadMe and Netlify

Guests: Jessica Parsons & Gregory Koberger

In episode 27 of JAMstack Radio, Brian is joined by Netlify Documentation Engineer Jessica Parsons as well as ReadMe.io founder and CEO Gregory Koberger for a discussion on the future of documentation and how more personalized API docs could benefit developers across skill levels, interests and languages.


About the Guests

Jessica Parsons is a documentation engineer at Netlify where she writes, gives talks and contributes code that helps developers get the most out of Netlify’s products. Gregory Koberger is co-founder and CEO of ReadMe.io, a platform for interactive API documentation.

Show Notes

Transcript

00:00:00
00:00:00

Brian Douglas: Welcome to another installment of JAMstack Radio. In the house we've got Jessica Parsons from Netlify.

Jessica Parsons: Hi. I'm sorry, I guess this is the part where I introduce myself.

Gregory Koberger: We're keeping this. This is definitely staying in.

Brian: We've got the other Jessica. We'll keep all this in for the record.

Jessica: There are a few, you know.

Brian: Jess, what do you do at Netlify?

Jessica: I'm a documentation engineer, which means that I write the docs, I code the docs, I come up with projects for making docs.

Brian: Documentation all related. Also in the house we've got Gregory Koberger.

Greg: Hi. My name's Greg and I'm the founder of ReadMe. Also documentation stuff but more so a platform rather than specific documentation.

Brian: Awesome. You mentioned ReadMe. What is ReadMe?

Greg: We got the name, obviously, from the file that comes with every software package. Which has been great because all my friends last year started watching Mr. Robot. I got a bunch to text me like, "Oh my God, they talked about your startup in Mr. Robot." I was like, "Yeah, that cost a lot of money. That was a big marketing deal."

We do documentation. The premise for the hope is, yeah, we do documentation, but I really want to push people towards less static documentation. There's always going to be paragraphs text and explanations but hopefully we try to show rather than tell. That's why we're trying to push documentation.

Mostly API documentation is what we do. The documentations are UX or UI for your API. It's how people interact with it. We want to make any website you go to, it knows who you are, it knows what you've been up to.

API documentation tends to be very static and shows the same thing to everyone. Our goal is to try to make it as knowing about the user as much as possible.

Tailor to the user. Maybe it's your first time, maybe it's your 50th. If it's your first time, you probably want just to get an API key and learn the basics. If it's your 50th, maybe the site's down or the API's down or your credit card expired or who knows what. Trying to take documentation. The reason we started was trying to make documentation a little more lively.

Brian: Awesome so when you say you're making it more lively and also improving this through the APIs, what does that look like? Are you looking at my code and then writing docs from that?

Greg: It's still a platform where the person will be writing their own docs, of course. But there's a few ways we try to make it a little more interactive. The first is with community. We have support forms. Anyone can suggest edits, things like that. The goal is to allow the users to ask questions and make changes and help you build your docs. It's interactive in that way.

But more so if you're an API, we have code builder where you can pick the language, Python Rails, whatever. You can fill out some information, you can copy and paste the code snippet, you can test the API out inline, and you can log in and stuff like that and hopefully see your API keys and have that all embeded.

We sell lots of paragraphs with text and stuff. Our goal is and always has been and definitely over the next few months is really to give people really interactive ways to consume and learn how to use an API.

Brian: "Documentation" is always a weird word.

Before I came to Netlify, because documentation's the best there, it was more of a dirty word. It was like a thing that we just did after the fact when we had time between sprints.

It was less of a focus despite the fact of literally GitHub, will initialize every repo with the readme, you have that option. Most readmes are really scarce. Did you see that and see a need to fill that gap?

Greg: I'm horrible at documentation, horrible at all of this.

Brian: So you started the company?

Greg: Yeah, exactly.I came from the opposite way, which was not that I liked documentation writing or whatever. But on the flip side, though, I loved using good documentation. Documentation that I really liked was stuff like Stripe or stuff like Twilio, those are the ones that get brought up all the time.

One thing that frustrates me a little bit is that, Stripe's great and I have nothing bad to say about them except, and it's a side effect, is that they popularized this three column layout with the black sidebar and everything.

I think the takeaway a lot of people had was Stripe's stacks was really good. I want to look like Stripe's stacks which, sure it's pretty I'm not denying that but the reason why Stripe's stacks are so good is because there's a lot of things they put into it. It knows about the user, it knows the most recent calls you made like the example API responses are actually like your API responses. It knows your API key.

They have this really cool thing where, let's say you've never heard of Stripe before, you never used it. You go for the first time. You haven't signed up. You can copy and paste a code snippet with a random API key in it and then when you sign up they actually sign that API key right to your account and stuff like that.

They just have done such a thoughtful job of everything that, yeah, the design's great but the reason why people love their docs, I think, isn't the design. If there's one takeaway I could push on people as far as Stripe goes, it's that again, looks are fun but the reason why you really like it is because it's so well integrated and it's not a static site that could be... I don't know if I said it right, here.

Jessica: You keep using that word. You're using static to mean something different.

Greg: I'm using static to mean PDS, of course. Whereas Netlify obviously the S's are static but there's still a lot of stuff going on that's not static. I'm not trying to use static as a dirty word.

Jessica: And it's a popular thing in docs right now. Static site generators are really taking off with docs, but not necessarily static.

Greg: We use React, so everything's static in the way that Netlify docs are called static I guess, and use APIs for the live stuff. I realized when I kept using the word "static" that what I really meant was...

One of our number one requests, I think probably is our number one request, is PDF generation. That's what I mean by static.

At no point should both of you be seeing the same docs, because you have different needs, different requirements, different skill levels, different API keys, different everything.

When I say static I don't mean you can't use Netlify.

Brian: Do you dive through PDF generation?

Greg: Oh, no, no.

Brian: That would be interesting. I guess if someone wanted to make a book from their documentation.

Greg: I think it's the bigger companies where they're just used to it. I don't know why. I don't know if it's worse internet or whatever, but it seems to be international companies seem to care a little bit more about PDF generation. It's less and less of an issue but I think airplanes and stuff like that are a reason.

At the end of the day, I don't know if people really need it or if it's just something that people think they need. As far as product stuff goes I'm sure you guys, if I get a lot of those, do you really need this or do you think you need this because you've had it for the past 20 years?

Jessica: Sound like an ages-old checklist. You just always have to make sure before picking a new tool.

Greg: We don't do PDF generation. There's a few people who have written open source tools that scrape the site and turn it into PDFs.

Brian: There's a few React ones. You mentioned checklist, Jessica. Do you have a checklist when you approach a new project or a thing you want to use that you are looking for, in the documentation?

Jessica: I wouldn't say that I have a list. But the interactivity is actually really, really awesome. It's not something I could put onto a checklist as well, though, because it's not as common as I would like it to be.

Greg: Yeah, I agree with that. Even on Ruby sites it's not as common and that's definitely partially our fault and it's definitely just partially that people don't think about it, I guess. Even just code snippets. When I use documentation the first thing I scroll to is, I don't read the paragraph text.

Brian: You copy and paste.

Greg: Yeah, then when that doesn't work, then I'll go back and read. There's a company I really liked. I don't know too much about them so I probably shouldn't talk too much, but here we go. It was called Runnable They were trying to do documentation in a new way.

It was literally just containers that you could run sample code in. The whole point would be that if Netlify were to use Runnable for their documentation it would be like you just create like 30 code snippets. They had some sort of technology that would run it and all that.

You could make edits and stuff and run it and it was really cool and I liked it because it was very use-case driven. You could play around with it you could tweak it, you could use it. They've kind of switched a little more to being just containerized stuff. Not sure exactly what they're doing now. You can't have just examples of course.

Jessica: Yeah exactly. You actually need the reference that goes with it.

Greg: But I did like the idea that they're focusing a little more on use cases. Because I think all too often API documentation tends to be very written in the minds of the developer as opposed to written in the mindset of, what do people actually want to use this API for?

Endpoints are very much like hosts/users/whatever. You can figure out what it's for but I do wish that API docs were a little more use-case driven and a little more heavy on the examples and you definitely need text to come with that example.

There's a happy medium, I think, where I don't think we should be going, "Here's this code sample, just go with it." Interactive examples where people can play around with it and touch it and feel it. First, I want to make the developers happy and secondly make it possible for non developers to use it because

we're getting to the point I think where people are becoming more and more tech literate without being programmers, and bridging that gap is really, really important.

Brian: Stack overflow engineers.

Greg: Which that shouldn't be an insult necessarily, because I do my own taxes and I'm really shitty at that. I do my own everything. People want to build code they don't have to have a CS degree and do it full-time. There's so many cool things you can build just to automate.

Netlify's a great example. I feel like you guys aren't like me but I assume a lot of your customers don't have CS degrees or aren't programmers. They just want to make a blog, they want to make a little app, they want to just build something. I think that's going to happen more and more.

To bring it back to Netlify, I guess you guys are just static stuff with APIs in the back end. It should be easy for people to cobble together three or four APIs and build something pretty cool.

Brian: I think our users, customers, they're kind of spread around. We do have a lot of beginners. We do have a lot of people coming from the PHP world where they could just throw together some code snippets and combine them and make an entire app.

But then we also have very advanced developers who just don't want to do all the manual manipulation of their CI and continuous delivery and stuff like that. It's hard to pinpoint, "Are customers in the one bucket?" Jessica actually handles some support.

Jessica: I started making buckets. I came up with like eight buckets and I was like, wait this might not be useful any more.

Brian: Yeah, "Let's fill all these buckets all the time."

Greg: You have 120 thousand different buckets where everyone's unique and slightly different.

Brian: One thing for reddable code and examples, I think React docs, it's repl.it. I actually have Amjad actually on the podcast who runs for Repl.it. Some day soon, Amjad, if you're listening. They do code snippets. Jess also has a bunch of code snippets as well.

Another really good example, I think they probably got it from Stripe, Graphcool, their docs actually embed. The Graphcool key for your project that your database is injected in the examples as well. When I was learning how to use GraphQL through Graphcool all the examples I could just copy, throw into my code, because it had my keys and everything related to me.

Jessica: It's nice when you don't have to copy the code and the key every time.

Greg: Yeah that's great. One thing that always really bothers me about docs is when there's just absolutely no code snippets. It's just so impossible to recompile a code snippet as an engineer from a list of parameters and a list of URLs into Python Rails or whatever.

Let's be generous and say there's 10 languages that 90% of people write. It shouldn't be that hard for doc writers to really have good examples that can be copy and pasted in a bunch of major languages.

If you're using an esoteric language or a random language, fine. But if you do JavaScript, PHP, Python, Rails, Java, and maybe three or four more, that's pretty good. It allows you do the work once and your users don't have to do the mental energy of piecing together. And since you are all encoded, "Oh, no it's not supposed to be, I forgot to paste this header in." Code snippet should be in my mind pretty pre-generated and ready to go.

Brian: You mentioned before that you started ReadMe because you had a problem that you wanted to solve properly but you didn't want to actually put the effort where's here's my problem where my documentation was an afterthought, so now you're actually in this documentation community, what is the community like?

I know, Jess, you actually speak at a couple conferences in the past and meetups, I believe? I know you've spoken at meetups. Collectively, what's the perception for automating your docs and being able to make this more entertaining?

Jessica: It's big.

There's a lot of talk about it in the Write the Docs community, which has conferences and a Slack channel, which if you write documentation, then I highly recommend it.

Brian: You recommend the Slack channel or writing documentation?

Jessica: Both. But if you do write documentation, I recommend the Write the Docs Slack channel and their conferences. They have a local San Francisco meetup and meetups in other areas related to some of the things with the checklists or types of docs.

I went to API the Docs in London, which is like a branch off of Write the Docs that's API-documentation focused. They're based in Europe and have done some conferences there. I saw a great talk by Daniele Procida, I probably pronounced that wrong.

Greg: I was impressed. You should just go on with it. I was going, "Damn that was good pronunciation. How'd she get that right?"

Jessica: He's done it in a few different places, but talking about branching docs and four different types. One of them is reference, which is just listing what all of your different endpoints are, or something like that.

One of them is tutorials, which is more like he uses a metaphor with cooking. The tutorials, you are hands-on with someone in the kitchen and you're taking someone new step-by-step through the thing.

Then there's the how-to's that are like, "I just want to do this." It's like a recipe. "Just show me that thing. How do I get an RSA key? I'm going to go to that GitHub doc for it again." The fourth one is discussion or things about the tech behind it. I think all of those things fit in there really nicely. Making sure that you cover all those bases is good.

Greg: I think that may have come originally from Jacob Kaplan-Moss wrote a really good article five or six years ago. Most of API documentation's been based on that list, but our preference guides tutorials and topical guides, is what he called them. Same exact thing but I like that Daniel, did you say his name was?

Jessica: Yeah, Daniele.

Greg: Put in the discussion stuff because I think that's really important, too. I find that's the Wild West where as a doc writer you're supposed to be telling a story, to a certain extent.

There's so much stuff you could put in and you don't want to put everything in, because then you just have really long docs that aren't relevant to people.

I'm a huge fan of the actual docs cover the 80% use case and then let the support forms FAQ, a good search cover the other 80% and the longer tail stuff.

I also agree that the Write the Docs stuff is pretty good. I found that I get invited to speak at two types of conferences. One is the writer eccentric ones and the other is the API eccentric ones and they are two very different communities.

I'm kind of in both because my talks are usually, "You should automate this stuff," and, "You should spend time and focus and write out this stuff because a lot of times the API communities are very much," into, just thought I'd generate everything, and you're good to go.

I think you should definitely be auto-generating a lot of stuff. But you should be auto-generating the reference-guide-parameter type stuff. If that's all you have and offer that's like handing somebody the thesaurus and say, "Learn English," or a dictionary.

It's a reference guide and it's supposed to be just a reference. It's not supposed to be your entire documentation. Whereas I've actually really impressed Write the Docs when I started going to meetups. There was really no automation. It wasn't really part of the conversation. Now it seems to be a huge part of it.

Jessica: Yeah, it's really picking up.

Greg: I think a lot of people think it's this or that, but it's 100% not that. There's things that computers are way, way, way better at. If you got 100 endpoints and you want to have code snippets in 20 languages, no human being can possibly do those without causing issues.

Whereas computers are great at that, whereas computers have no idea of the context. They don't know which of the 100 endpoints is more important. They don't know which will go well together. They can't explain the philosophy behind it and why you want to use the API and why you want to use a particular endpoint and how to use it and stuff like that.

Jessica: I feel like now that the conversation is sort of turning to not one or the other it's bringing both into it. I feel like tech writers resisted it at first because often developers were like, we can just generate it all and that's all you need. "Get a Swagger file and you're done!" Then the writers are like, "No, you actually need a little bit more than that." Now they're like, "Oh yeah, we actually do need both and now they're working together."

Greg: It's lovely.

Brian: It's interesting you bring it up that two different communities are now converging, I guess sort of converging.

If we zoom out really quickly, I just had a thought. Do you think it's because the term "full stack developer" is now more of a dying term? Before we had people who could touch everything, pretty much all parts of the stacks, they could do everything. They could also write docs in addition to that.

It seems like now, even in the programming world, we're starting to realize there are edge cases that you can't just cover with only one, solo developer. You have to have a specialization like a documentation engineer.

I bring this up also because next week is DevGuild which is a Heavybit conference. I went to last year's, actually last year's last year's, so two years ago. One really good talk that I got from the guy from HashiCorp. He was talking about zero to getting your project up and running and that whole story between of they found out about ReadMe.

"What's the next step of actually getting this project running?" That story can really get really awkward if it's just reference material. It's like, "Run this command, run this command, okay, you're good but you have no idea what you just did." That in-between is definitely needed, I think.

I'm glad to hear that there's people talking about this, because I've been in a point where, I remember when I first learned Node back in the day and people were switching from 0.8 up to 12, or whatever that problem was. There was hardly any documentation on some of the Node libraries I was trying to use and it was painful. It was just all command line. Things that you just did.

Jessica: It usually goes along with something that says, "It's easy, you just do this."

Brian: "Simply do this."

Jessica: Yeah, "simply do this" and then it just shows lines of code. I teach a lot of new developers and when it just says it's easy and then shows you a command line line and you're like, "Does that mean I have to go in the Terminal thing? What do I do with that?" There are people who could totally use your stuff that just haven't used that yet. Not that you have to teach everybody to use it to be online.

Brian: I do some tutorials as well, and people call me out. Sometimes when you do a command-line thing to run, you put the dollar sign first to show it's command line. But new developers will be so confused about that.

Greg: It's not obvious. This is so obvious for me, I wouldn't think twice about it.

Brian: I run the dollar sign, nothing's happening.

Greg: We started doing this thing on some of our site where we'll have a node snippet but you can click in see how to install node. You can zoom if you need to do that. "How to install the request package." Stuff like that, that even just giving a code, even if the code seems perfect where do you put it? I don't know.

I remember the first time, I was like, "Where do I run this?" They're like, "The command line." This is years ago. I'm like, "How'd you know that?" And I was blown away.

Jessica: It's like, where in the command line? That's a big thing, too. Do you do it in the project folder? Do you just do it anywhere you feel like in there?

Greg: It's different, too. It's just different. It's crazy. There's one other thing I wanted to touch on, that I think as far as writers go, I feel like I don't see ReadMe as necessarily being a platform for writing or a platform for autogeneration or anything like that. It's more like usability, and people express usability in different ways.

I think tech writers are usability and their tool is a language like writing paragraphs of text and stuff. There's bad tech writers of course just like there's bad anything else. The bad tech writers don't think of it that way but the best tech writers I know think of themselves as usability-type people that just happen to express themselves via paragraph text.

That's what I really like about going to Write the Doc stuff, is that it seems like the good writers tend to be phenomenal. I don't know how some companies are so lucky to get such good writers. It really shows when you get to good docs and a lot of times you don't even realize it, because you're just like, this is really easy and you don't realize how important the curation on the side of the writer was and stuff like that because

it's really easy to write docs but it's really hard to write docs that are easy to use.

It's a tough balance between automation and making it so that "one click and this magically works," and giving people a way to write the docs and all that stuff. That's the bounce we're trying to strike.

Brian: You mentioned finding good writers. Jess, you have a entirely different background that you didn't really mention. You want to talk about your background and how you got to this point?

Jessica: I was originally trained as a teacher. I taught elementary school. First through eighth, at one time or another became a technology coordinator for a school. Progressively did more and more technical roles, started making websites about 10 years ago professionally.

Somewhat recently decided to mix those two thing together, the teaching and the coding, together. I teach workshops and I also for a little while taught for a boot camp and reminded myself that I don't like teaching all day long. Now I like being able to mix it and actually have time to code and time to write and time to show people how to do things.

Brian: Which is awesome because you always bring a different light to our documentation. You showed that really quickly because our documentations are very dry. I think most of the customers realized this as they were using it. You bring in the "why" and the "how did you get here" to our documentation. I appreciate you being on the team.

Jessica: Well, thank you.

Brian: I'm really opening up right now. Because of that, I think a lot of it just finding people with more than just one skill set. It's great that you can generate lines of code from C++ commands, but it's also great if you read books sometimes that are not technical so you can mirror the world, so that way people who want to come in new and not understand they can find that story between the code.

Jessica: I think at the end of the day,

your API has one use and that's to be used. Anything you can do to make it used is great.

Twilio just released something that was a game where you play along this old-school, 8-bit type game. You learn how to use Twilio. Like, why not? Anything you can do to get people to use your API is awesome. It's a little more funner light hearted or explains things. No one wants to read dry paragraphs and paragraphs and paragraphs of text.

An API is being easier and easier to use, which means that it's not like one of those old, you have to get a gigantic book of how to use this system or something. APIs are pretty easy to use.

Anything you can do to make them easy to use, that's the umbrella that we consider documentation. I don't think documentation is just paragraphs of text, I don't think it's just reference guides, I don't think it's just support forms. I think you get a healthy mix of all of that. That's our niche.

Jessica: I think it's interesting, too, that you say talking about, for one thing I think a big thing about teaching is putting yourselves in the shoes of the people who are trying to learn it. There might be the people who are just like, "Tell me the commands that I can do and I know what to do with them," and then there's the people who need more guidance or things like that.

One thing I like about your emphasis on having stuff be different for each person who comes is that really reminds you that because you can make this dynamic and specific to each person, it makes you think about that and what that means to make it specific to each person.

What is this new person come in? What are they going to need? What is this person who comes in like they've done lots of times?

Nobody wants to read paragraphs and paragraphs of text, but how do you handle all of those different use cases in one single static page? That's where the interactivity comes in.

Greg: That's why O'Reilly books who are so gigantic, because they're aiming for all sorts of skill levels and they have no way to know, "Is a dollar sign enough to signify that it's a command line, or do I need to write a paragraph of what the command line is?" It's really tough and obviously there's no way to magically know peoples skill level.

We don't really do a great job of this. We do it a little bit here and there but when people self-report and expand to get more information is the path we're trying to go down as far as showing as little as possible right away and letting people delve in and expand and get more information about how to install Node. "What is Node? I don't know anything, where should I start?" That kind of thing.

There's also people who documentation's important to that will never write a line of code. A manager might need to be sold on something. There's a lot of marketing stuff involved in documentation. DevOps might need to know security stuff, who knows.

There's many many different audiences for documentation and they all need different stuff, and all too often I think when I write documentation, know that I'm very bad at putting myself in other peoples shoes. I'm just like, "Yeah, of course you just URL encode that," or, "Of course you have to include that header, that's just obvious." When you write it and get people to step back and think about it is really really tough.

Brian: We spent a lot of time talking about documentation. We haven't actually spent too much time talking about ReadMe. Are there any killer features that help kickstart the documentations process that the users might be interested in?

Greg: We do documentation. We both do product documentation and API documentation. There's a lot of stuff where, because they said the marketing thing, we think APIs are very critical to peoples business so you want to be able to customize it.

We do all that stuff. Ways to write paragraphs with text, ways to do support. One thing that we have, that feels really cool to me, is in comments you can write the documentation and sync it all up and it will automatically keep your docs up to date which is really nice.

That's just the reference guides. That doesn't help with the actual writing of the real docs. To keep the reference docs up to date with your code is really nice. You can just put it as part of your CLI and just auto generate the docs and keep them updated.

Jessica: Do they do version tagging?

Greg: Yeah, the way we do it is, for better for worse, use OpenAPI Specs which is used to be called Swagger as our way of the standard that you upload and that allows you to have a version in there.

The reason I was hesitating on this because I have a very love/hate relationship with Swagger. On our end it's really nice because we just have one format that we're like, "Use this format," and people can use it. That's nice but I think the hate I have for it, I've started to realize, is a little misdirected.

It's not really that I hate Swagger. Swagger or Open API Initiative, Open API Spec is the best tool, I guess, for what they're trying to do in the sense that RESTful APIs are very very complex, and Swagger has relished in that complexity and has thousands of options so you can document any API.

Whereas my problem with that, I think, is that I don't think everyone should conform to any specific standard or anything. But the whole point of API is you're supposed to be able to connect two systems together or whatever and this, "no best practices, do whatever you want" type mentality, and there of course are best practices. Everyone has different opinions, and all that.

It's just such a Wild West with APIs that if I were to describe an API to any of you and you didn't really know computers that well, I could make it sound really great.

"A RESTful APIs the standard interface where two systems can connect and talk and share data." You think it's really easy just plug and play, but the amount of just little details that you need to know, the things that keep you and me employed by the little idiosyncrasy stuff, it gets a little taxing. I think when there's just thousands and thousands and thousands of configurations and ways people do their APIs. The way people pass their API keys and stuff like that.

I think that's my hatred for Swagger is I think APIs should be really simple to use and it seems like it should be really simple because in concept you throw data at it and you get data back. Even little things and I could sit here and obviously tell you the difference and all of us could. You're passing on data. Is it a path param? Is it a query param? Is it a form data? Is it a body data? Is it a cookie or is a header? That's six different ways to passing data.

I could, of course, explain the API should be this or the reason why it's this way is whatever or little things like gets can't have a body. Deletes can't have a body but posts can have a body. Again, I know the difference, I know why and all that but it just becomes very in my mind very confusing to explain to anyone.

That's my frustration with Swagger is that, it's not Swagger's fault. They came along when we were just trying document, how to build an API. They did nothing wrong. It just gets a little frustrating to me how complex something that should be very simple is. That's my Swagger rant.

Brian: On that note I'm going to transition us to picks. I really appreciate you coming in and talking about documentation, both of you guys. I've actually learned a lot and I've actually opened up my mind to, what am I doing wrong?

I did a lot of wrong but what I don't do wrong is picks. You guys are familiar with picks. Listeners are familiar with picks at this point. Anything you're jamming on, hence JAMstack. My first pick is actually tortillas.

I know this is going to sound weird, but a couple episodes ago I was talking about how I was watching Narcos. I would only watch Narcos on the airplane as my thing to do because you can download episodes on Netflix. That's not the pick, but I was watching one of the later episodes in the second season where the antagonist was actually cooking tortillas on open flame on his gas stove. When I saw that, I was like, wow.

Jessica: I learned that from my uncle.

Brian: That's how you eat corn tortillas. Because I used to microwave them to make sure they gel better and all that stuff. They always taste better when you get them out of a taco truck or anywhere else. Mind you, I'm from Florida so we don't have tons of Mexicans there, so tortillas is not a big meal option. Excuse my ignorance.

Usually I always want flower tortillas but now I love corn tortillas because in the Bay Area we have gas stoves for some reason. I cook all my tortillas on an open flame on the gas stove. Check out the last episode of season two of Narcos and I think you'll catch my drift. It's pretty awesome so I've been making tacos and pretty much a lot of tacos.

Greg: I feel like you should clarify for people who don't know Narcos that it's not a cooking show. They're going to be very surprised when they're like, "I love cooking shows."

Jessica: Don't watch it with an appetite.

Brian: It's actually a way different cooking show. They don't cook food on that show. We'll leave it at that.

Jessica: I once made tortillas by hand, corn tortillas.

Brian: Oh really? That's step two of this journey.

Jessica: Yeah, you totally should do it.

Brian: Any picks you guys got for me?

Jessica: One thing actually that I am doing later tonight, I'm teaching a workshop for Girl Develop It.

Brian: There's a pick.

Jessica: It's something that I've been involved with for a few years. I actually took a couple of workshops a few years ago. Girl Develop It teaches low-cost coding workshops to adult women, despite the name, and do that across the country.

We have 46 chapters or something like that. Also teach people of all genders but the focus is on women. It's mostly, I'd say 90% or more women in the classes. You don't represent your gender when you ask a question, which is kind of nice.

It's a really great organization and if there's anyone who is interested in learning coding or you know someone who is, I highly recommend getting involved with your chapter. Or if you're just volunteering to help out that's another thing that's really cool.

Brian: I know that there's a chapter in the South Bay, is there one in SF up here?

Jessica: There's one in San Francisco. It's actually one of the biggest. It's actually really big, been around for a while. That's where I'm teaching tonight. It's really just a great group of people putting it together.

I've been involved in a variety of nonprofit groups around coding and things like that. There is one also in San Jose and there's one that just started recently in East Bay.

Brian: I'm sure you've probably checked the website. They probably have the chapters listed.

Jessica: Yes they do, at girldevelopit.com.

Brian: Cool, awesome. Listeners, check it out.

Greg: Sounds great. I'll land some place between tortillas and teaching under-represented minorities throughout their careers. One of my recent obsessions for team bonding stuff, because now I've gone from programmer to being more of a manager and stuff, my go-to obsession as anyone on my team will tell you is for team bonding is escape rooms.

Every time we travel I make my entire team do an escape room.

They have done so many escape rooms because I force them to do it. They're really good for working together as a team and figuring stuff out and communicating. For people who have never done one, it's basically an hour-long themed puzzle where, maybe the topic's Sherlock Holmes or a diner or something like that. There's a vague storyline.

It's just seven or eight puzzles or eight puzzles. It's less about figuring things out and more about communication. You need two people or you need to think of a good way to figure stuff out, and I find myself a lot of times yelling at people and being like, that's a shitty way to communicate because you're frustrated and there's pressure.

It doesn't really matter of course because it's just an hour long and who cares, but the clock's ticking down, there's pressure. That's my go-to team bonding experience recently. That's my random pick.

Brian: If the team doesn't collaborate enough and get out of the escape room do you hire new staff?

Greg: They get fired, yeah. I'm on my seventh team at this point, it's not going well.

Jessica: They're still in the room, actually.

Greg: I just leave them there.

Brian: If anybody's looking for a group of engineers, they can't solve puzzles but they can write code.

Greg: That's my pick, so some place in between the two I guess.

Brian: Awesome, appreciate it. It's definitely in between the two. I don't know if it would beat tortillas but that was pretty good. Greg, thanks again for coming and talking about ReadMe.

Greg: Thank you for having me.

Brian: Thanks for talking about documentation with Jessica. And listeners, keep spreading the jam.

Want developer focused content in your inbox?

Join our mailing list to receive the latest Library updates. After subscribing, tell us your preferences to receive only the email you want.

Thanks for subscribing, check your inbox to confirm and choose preferences!

You've been here a while...

Are you learning something? Share it with your friends!