March 22, 2018
Ep. #27, API Documentation with ReadMe and Netlify
In episode 27 of JAMstack Radio, Brian is joined by Netlify Documentation Engineer Jessica Parsons as well as ReadMe.io founder and CEO Greg...
In this episode of JAMstack Radio, Brian is joined by Richard Feldman and Brooke Angel from NoRedInk.
About the Guests
Richard Feldman is Director of Engineering at NoRedInk. Richard is experienced in IT project leadership, software architecture, web app development & UX design. Before that, he co-founded Stellar Systems and worked as Data Visualization Developer at Monsanto.
Brooke Angel is Software Engineer at NoRedInk. Prior to that, she worked as Senior Teaching Assistant at App Academy.
Brian Douglas: Welcome to another installment of Jam Stack Radio. In the room, we've got Brooke Angel.
Brooke Angel: That's me.
Brian: Cool, and then the other side of the room, we've got Richard Feldman.
Richard Feldman: How's it going?
Brian: So I have you guys here to talk about Elm. Actually, Richard, what is Elm?
We introduced Elm in 2015 and we recently crossed the milestone of 100,000 lines of Elm code in production. And for the entire time we've had it in production, it has not thrown a single runtime exception.
Brian: Cool and would you say in production... sorry, we didn't preface this. You guys are both from the same company, No Red Ink.
Brian: Cool. So, when you say in production, you're talking about No Red Ink.
Brian: Not just the world.
Richard: Right. Although, I should add that, I've actually talked to quite a few other companies using it in production, and that's always the first question I ask them "how many runtime exceptions have you gotten?" Still the grand total is zero across all of them. Not just us.
Richard: Yeah, so I guess, that's, I can talk to that. So I signed onto No Red Ink a long time ago, like, about three and a half years ago, and back then, this is like before React came out. And basically, we had a bunch of different stuff going on with our stack, and when React came out, we're like, "this is really cool. Let's adopt this." And so we kind of started using React, it sort of took over our front end, and then I'd been doing some Elm on the side, just kind of, you know, on a side project.
And really liking it, being really impressed, and we had this one project that took a long time, and I kind of realized, after we did the project, "wow, knowing what I do about Elm, this project would have gone a lot better, would have gotten done faster, the result would have been more maintainable, if we'd done it in Elm."
And I feel like I kind of made a mistake by not even trying to introduce it. So, basically, what I did was I just started introducing into it like one small part of one page and we got that into production, it kind of grew from there. And now, today, it's sort of just taken over our whole front end and it's pretty much what all of our front end folks spend all their time doing.
Brian: Cool, and then speaking of those front end folks, Brooke, so I wanted to know your background because I know now you write Elm, so I'm very intrigued about your background coming to No Red Ink and then your experience writing Elm today.
Brooke: Yeah, totally. I'd be excited to talk about that. So, I'm actually pretty new to No Red Ink and I just started working there in January. And before I started there, I attended one of those newfangled programming boot camps.
Brian: Oh, I've heard of those.
Brian: Cool, and so you're doing it full time? At the moment?
Brooke: Yeah. So far, I've been working mostly on front end stuff, so full time Elm.
Brian: So you're writing front end code.
Richard: Uh huh.
Brian: It goes to a compiler?
Richard: So the compiler does both of those things, basically.
So part of the language design is trying to make it so that more things can be caught by the compiler. So, you don't have problems with null or undefined because the language doesn't have null or undefined. Instead, it has these different constructs that let you express the same idea, but in a way where the compiler can really easily check and verify that you're not forgetting to check for the possibility of, you know, a value being missing, things like that.
Brian: Yeah. Had a follow up question but I completely forgot what it was going to be. Oh, I had a joke. So you didn't talk about what No Red Ink is. Do you want to explain that real quick so I can make my joke?
Brooke: So No Red Ink is a program that is used in a lot of schools for kids to learn grammar. So, an example of a lesson that we would have would be, a kid could learn punctuation by dragging commas to the correct place in a sentence.
Brian: Yeah. OK, so, I'm sorry, did you have a follow up for that?
Richard: No, now we've gotten into writing, too. So, used to be just grammar, but now it's both.
Brian: Cool, so you guys are compiling errors and exposing those, so with Elm, is that why you guys are such big fans? Because you're really into grammar and grammar checking? Has no one ever thought of that correlation before?
Richard: I think you're the first actually.
Brian: Oh, wow, OK. Well, I've got your marketing pitch for you.
Brooke: Well, languages do all have to do with grammar, so. It's that we're using a nice language.
Brian: Yeah, that's very interesting. And then, so did you have like coding experience before your boot camp and then going into No Red Ink or is it all through the boot camp?
Brooke: I did. I took one intro to programming class in college, and this was back when I was studying neurobiology and I was contemplating learning coding to help me with my research. So I knew some Matt Lab beforehand.
Brian: OK, yeah, I have no idea what Matt Lab is, but it sounds fancy.
Brooke: Used for sciencey things.
Brian: OK. Cool, so you came in with no experience other than your boot camp and then day one you started writing Elm code?
Brooke: Yeah, pretty much.
Brian: Wow, OK.
Brooke: Well, I guess, technically, day one I got my environment configured. Days two through five I was sick with the flu and then day six I started writing Elm code.
Brian: OK, well, within roughly a couple weeks, you were writing code. Which is actually phenomenal. I think that's really awesome and so actually, I don't have a lot of Elm experience. We do a little bit of Elm at Netlify. Which I've been tinkering around with, trying to help out with, which I've not done, as of yet, because I'm way too busy. But I do have experience with types. Coming from Go, which is not as strongly typed.
But with that being said, I have experience with working with types and having the compiler. It actually makes it easier for me to learn Go code that way. So I think, if I ever finally read Richard's book and then actually contribute code to my project then hopefully I'll have that same experience. So I think there's a light at the end of the tunnel. I'm actually excited to eventually use that.
Brooke: Yeah, totally.
Brian: Cool, and then, so when you guys say front end Elm, like, can you basically do anything in Elm that you could do in the front end? So like tile stuff, animations, et cetera, et cetera? Basically what I'm asking is, is there any limitations to choosing Elm as your front end, as far as accomplishing modern front end stuff?
Brooke: Yeah, I'd say, so far with what I'm doing, I haven't really encountered any hurdles.
Brooke: Oh, yeah, I guess I did.
Brian: It was that easy, huh?
Brian: How long had you been at the company at that point?
Brooke: Say a month.
Brian: Oh. That's not bad. Well, I mean, yeah, we're only a few months away from your probably start date, so you got like three or four months into it.
Brooke: I think just coming up on three months, yeah. Three months into the Elm forest.
Brian: But when you come after something like that. I don't know if you guys have a moment version. That was what I was coming to mind, maybe a moment library because I always reach for that and I know it's huge. But I'm like, I just want to do this one thing in moment, so I'll install the entire project. So something as simple as that, when you come up to something that's not been solved in Elm, like what's your approach to solving that? Do you first go to interrupt or do you go to like, maybe we should write something new?
Richard: I usually try to write something new. It's kind of an exciting opportunity. If it's like, if it's something manageable, right? So Moment JS, of course, is like an enormous date manipulation library, but probably what you need, like you said, is just like one small part of it. So as it happens, there's already a date library out there, but you can always either contribute to that, if nobody's written the exact function you need, or just you know, start a new package, if it's something where nobody's done any work on it yet.
Brian: I know, obviously, No Red Ink uses Elm. Are there other companies out there using Elm in production that has many lines out there as you guys that are supporting the language, as well?
Richard: Pretty sure we got the most. I haven't heard of anybody having as many as we do. As far as lines of code go. But I definitely, I mean, I talk to companies on a pretty regular basisand I'm surprised because I don't know where they came from. Like, a lot of the times, they're just, you know, sort of like off the radar, like they don't really participate in like community discussions or like Slack or you know, message boards or anything. But then they'll just be like, "Oh, yeah, we have 20,000 lines of Elm code. Like, who are you? How long have you been like that?"
So he's actually a go programmer, and he's very into all that ecosystem and backend infrastructure and I was like, "oh, I just want to build this one thing to solve our problem." And basically our problem, I'll explain it because I'm sure the listeners probably curious. Netlify, we host websites. That's simply, what we do, basically. But when you deploy a deploy preview, like a GitHub PR, you can click that preview and see a live version of all your changes that are in your PR.
Really cool. Not really cool when you do a blog post and it shows up on Hacker News. So we basically added an Elm project as like a context recorder and so every time you run a deploy preview or not production, in our app, not a lot of people use it outside of us, we're still tinkering with it, but it will tell you exactly, this is not live code, this is actually on this PR, and this commit, so click here to see changes, click here to go see the PR. Super valuable, very helpful, especially when we have like support tickets and like, "hey, we solved that problem, we haven't deployed the blog post yet, so here's a link."
And that's basically what happened. Someone took a link from our support ticket and was like, "Oh, this is so awesome. Hacker News, front page." And like, "oh, no, don't do that." So now we have basically a warning that says this is where you can see the code. Super straight forward, actually read through the code the night that I met with you, was able to really grock and understand exactly what was going on.
Didn't have any idea of what to do with it, but we actually do have it into like a web pack plug in, too, so it's call context recorder. So if you look for the context recorder web pack plug in, you can just drop that into your web pack config, and then if you're using Netlify, it will know to put that up on the bar for you. So, super straight forward, but also, wanted to bring up that the fact that you guys converted, if that sounded right, you guys converted your, I guess, previously React app into now Elm, piece by piece?
Brian: So how was it, because I know Elm is like this, not infrastructure, it's got like its own ecosystem. So how did you approach that? Did you build like small Elm apps, similar to what I just explained, here and there? And then eventually you found that this was an Elm app altogether?
Richard: So, initially, we used it just kind of for one part of one page, but then it was sort of like, "OK, we're making a new page, we liked that small bit we did before, let's make the whole new page in Elm." And then, "OK, the one after that in Elm." And "oh, we've got a designer now, so we'll redo this other page, when we redo it, let's redo it in Elm." And it was more like one page at a time, for the most part, then one part of one page, except for at the very beginning.
Brian: OK, yeah, I like the approach. I mean, I'm a React developer at the moment. We write all our code in React today. But I like that we could transition. We transitioned from Angular to React in the summer, and I like that we could take per pages and just render those React, which was totally fine, and I like the approach that we could pick a problem and solve that in Elm and then throw that in our production build.
Just super straight forward. I like that approach, and I like that there's a way for someone new to step into Elm and give it a try. I'm not sure where I heard it from, but things like, I think we wanted to attempt it, but we didn't do it yet. But like the credit code modal. Like when you enter the credit card, like you want to make sure those are type checked. You don't want to just randomly put sequel commands where you should be adding like credit card numbers. Not ideal, I think most credit card forms protect from that. But just something small like that, where you could just, it's a modal, throw Elm on there, or it's a context bar, throw Elm on there and just see how it works.
Richard: Definitely validate that one on your backend, too.
Brian: Yeah. Obviously. Well, Jam Stack, we're very big in the API, so obviously we'd use BrainTree or Stripe or something. But cool. And then, so I guess, with that, like where, if I wanted to start Elm today, like I really want to scratch an itch, I like what was talked about, like, where, what sort of things would I go through to figure that out?
Brooke: Oh, goodness, well, I guess I did this recently. Well, one way to do it is to dive into a code base that's largely Elm on the front end and just start hacking at that.
Richard: We're hiring if you'd like to do that.
Brooke: Oh, yeah, we are hiring. The way that I did it mostly outside of just working in our code base was working through the Elm tutorial. And from there, seeing.
Brian: Is that elmtutorial.org?
Brooke: Is that elmtutorial.org?
Richard: The official guide is guide.elm-lang.org.
Brooke: Yeah, and I started off by working through a few of those tutorials, and they start off pretty easy, like, get a button to render on the page. Get a button to increment a counter, things like that. And then once you work through a couple of those, it becomes easier to start working on your own small projects.
Brian: My approach that I've had so far is every six months I basically relearn the syntax and now I actually have a project to look at, so it's actually a lot easier to stay consistent on that. Well, not really. I haven't been consistent. But it was really nice to actually go to the code and walk through and figure out what was going on. As far as the project I mentioned. So, super cool, and then Richard, you also have a book, as well?
Richard: That's true, yeah. Elm in Action from Manning Publications. It's, in early access right now, so you can get about half of it. Still writing the second half. Also front end masters. There's like a two day Elm workshop that I did for them, which is actually more complete than the book, at this point. So happy to recommend both of those.
Brian: Yeah, cool, and I know, there's like Elm conferences, or meetups at least, outside the US, across the country? Does it seem like the community is kind of picking up at least?
Richard: Yeah, it's great. So last year we had our first conference, which was in St. Louis, was attached to Strange Loop. So that was Elm Conf, and then next we have Elm Europe and Paris, in June, and then also Elm Conf is also going to be attached to Strange Loop again next year. So, really exciting to have gone from just like the first Elm meetup I went to in San Francisco was almost three years ago now. And it was like 15 people. And now I just went to one in London and it was about 100 people. Yeah. It's really, really growing. It's cool.
Brian: Yeah. Actually do you want to explain how the meetup structure is?
Richard: Ok, sure, so, basically, the way we do it is kind of a hack night format. So we don't do talks, instead what we do is basically people show up and if you've got some project you're working on, we just kind of go around and say, "Hey, who's got projects? Just give us a 30 second pitch of what you're working on and see if anyone wants to come pair with you on it."
And then we always have some number of people who are sort of brand new and want to just kind of get a quick intro. Then we have some number of people who just want to kind of have discussions about various things, collaborate with people. So it's like a very laid back, just kind of free flowing, just like fun way to come build stuff.
In the early days, Evan did talks like a lot of meetups do, and he noticed people were not really building things. And he really want to just give people time to build stuff and learn from others. And so ever since he switched to that format it's been working out really well.
Brian: Yeah. And I like it, too because like, for example, when I met you at the last meetup, I was able to share the code that my CTO wrote, with the guy that was sitting next to me. I was able to explain it and then talk to it, and then like get feedback on like how to approach it or how cool it was or how cool it wasn't. And then I was able to actually figure out what everybody else was working on, too.
So I think one of the biggest problems, like trying to learn a new language or new framework is like, I have no idea what to build. Like, there's enough to do apps out there. That you don't need one more Elm to do app. But it's really interesting. I met one guy a year ago who was building a chat. He worked at ZenDesk. I doubt it's actually in production at the moment, but it seemed like he was going off on his own world to build this chat app at ZenDesk. So similar to intercom, basically.
Richard: Yeah, I know ZenDesk is either already or about to be using Elm in production.
Brian: Oh, maybe. I assumed it didn't work out.
Richard: I don't know if it's that project.
And it's just very nice to not be constantly encountering run time errors.
Brian: Awesome. Well, with that being said, unless you guys have anything else you want to add about Elm or anything else, when's Strange Loop, actually? Summer time?
Richard: September. So, Elm Europe is in June, in Paris and then yeah, Elm Conf will be in September. I forget what date, but it's online.
Brian: Cool, hopefully I'll have a project to share by then. I'll submit a CFP.
Brian: Cool, well, with that being said, we'll go ahead and roll into the jam picks. These things you're jamming on. Stuff that really gets you going, while you're coding or not coding, like me. And doing podcasts. So, anyway, yeah, so I'll go first. And if you guys have extra picks to add on to this, because I didn't mention that they don't have to be technical picks, they can be fun picks, as well. Technical picks are fun, but I don't want to distinguish that you had to do a coding pick, but I say that because my first pick is the hot bar at Whole Foods.
Actually just hit that up on the way in. I am actually doing a vegan diet for the week. So I like to challenge myself. And I am nowhere near a vegan, never been a vegan. But I'm trying really hard to do it and I had nothing to eat and my wife's out of town, so I got a whole bunch of bananas. So I had two of those for breakfast. And I had to come in here to get something to eat, so I'm like, "Oh, where can I go?"
And I rode my bike in, so I was like, "Oh, Whole Foods is on the way." So I went there and just looked like for anything that did not have milk or cheese or anything like that and I was like, "Oh, cool, I can eat all this." So, it was a very quick snack and I didn't have to think too hard. Coincidentally, I do have a vegetarian Chinese food restaurant near my house in Rock Ridge, in the east bay.
So, I don't want to pick it because I think their food's horrible, but I do have options if I do get desperate. In addition to that, I also want to pick the context recorder, which is a web pack plug in that uses Elm. So if you do use Netlify as your hosting provider, definitely check that out, so that we don't have problems like we did. And also play.netlify.com. It's a playground that's written in Elm. And it's written to test redirects and also header things, as well. So if you ever wanted to test like, if redirects work. We actually have a redirects feature in Netlify, so if you wanted to test it out, it's in our documentation, netlify/docs if you want to check it out as well. Cool, and Brooke, did you have a pick for us?
Brooke: Yeah. Although, first, commenting on the vegan diet thing, I too, recently became a vegan a couple months ago, or a fake vegan anyways. And so I've been having to revise all my recipes to be vegan inclusive and yeah, would love to talk to you about that later. But anyways, my pick for the week. So I also recently got into carpentry around the same time that I got into this whole vegan diet thing, and I've been attempting to build all sorts of things.
And the first thing I built was this work bench, which was like setting up my environment. And that was pretty difficult. It was my first carpentry project ever, and it didn't turn out great. But just yesterday, I finished my second big project, which was this nice shoe rack shelf type of ordeal, and I'm super, super excited about it. It took me like four weeks longer than I expected it to.
Brian: That's pretty much how code is.
Brooke: Yeah, I keep thinking about it in terms of parallels to code. And I have this problem when I code where I don't think about what I'm doing in advance, and so I'll just code, code, code, code, and then I'll sort of run into a problem and be like, "Ah, I should have planned for that." And it was sort of the same type of thing with my shelf, where I thought it through most of the way, and then there were these certain pieces that I didn't know how to arrange, like the table top of this shelf.
And so I just, I got to that point, I was like, "oh crap, like, I don't even know how to attach this thing." But eventually, after some screw placement, I managed to attach the top of the table and everything turned out great and now I have a very fancy shoe rack that I made and everything is awesome.
Brian: Wow. That reminds me of the tweets that go around all the time that's like unit testing versus integration testing. And how like, how they have a bunch of pictures of people building stuff, and they're just like epic fails that don't work because they unit tested each part, anyway. First thing that popped in my mind.
Brooke: If you're going to build a shelf, think it through the whole way before you start just screwing things on. Lessons learned.
Brian: Do you have like, I'm curious, do you have like a space where you actually do your carpentry, or do you just like in your apartment or whatever?
Brooke: Yeah, I was lucky enough to find a house with a garage, so it's become the workshop.
Brian: OK, cool, awesome. I also have a house with a garage.
Brooke: Garages are great.
Brian: I don't do any carpentry, though. Richard, you have any picks for us?
Richard: Yeah, I got one. So this is Surge Teaches Mandarin. So I've been attempting to learn Mandarin Chinese. And so far, I know almost nothing about it.
Richard: Yeah. Work in progress. But yeah, I thought this was a pretty cool way to learn it. He has like an interesting basically short podcast format. Where he just sort of like talks you through a lesson and like pauses so that you can say the word back and stuff like that. It's been a really long time since I learned a language, like, since I guess middle school is the last time I tried to pick one up, so maybe this is just par for the course for everybody, but so far I found it useful.
It's really a weird mental shift trying to wrap my head around some of the concepts. Like one of the first lessons is he talks about like the word ma. But he says it like, "There are four different ways to say it." And all of them, like, have different meanings. And all four of those mean different things. Just based on the different tones that you use to say it.
And this is very alien to me because like in English, you can have different tones and maybe it means you're being sarcastic versus something else, but it doesn't actually mean a different word, right? Usually. So that's been an interesting shift to sort of deal with and my buddy Surge has been helping me out with that.
Brian: Cool. And do you see any parallels in learning an actual talking language to programming languages?
Richard: I guess there's, the mindset shift probably has some parallel with like FP versus OO. So one of the things that I see in a lot of beginners in Elm have to kind of like come to grips with is, especially as you're scaling applications, when you're like, Elm doesn't have a component system, it doesn't have objects. Well, you know, so like, if you're used to scaling, using those concepts, it's like, kind of a different thing to deal with one atomic notion of application state and how to scale that just using functions.
And turns out, there's plenty of good ways to do it, but they're non-obvious if you're, you know, really comfortable and familiar with the object oriented way.
So I'm very intrigued. I'm going to Europe this summer, so I'm going to try to, I'm not sure what language I'm going to try to hone in on, because I'm going to go to a couple of different places. But I want to attempt speaking the native language while I'm out there, so who knows? It might be Spanish because I'm lazy. Because I already know a little bit, so. Cool. Well, guys, thanks for coming in to the studio. All the way down the street.
Brooke: Thanks for having us.
Brian: Cool, and I really appreciate you sharing your experience, Brooke, about approaching the language of Elm as a new programmer, at least. And bringing your expertise, Richard, as well. I know you're an expert at being on podcasts, talking about Elm, at the moment.
Richard: I've done a few.
Brian: Cool. Well, with that being said, keep spreading the jam.
Brooke: Thank you.