[00:00:05] SY: Welcome to the CodeNewbie Podcast where we talk to people on their coding journey in hopes of helping you on yours. I’m your host, Saron, and today we’re talking about documentation with Eddie Hinkle, Lead Front-End Engineer at Glassdoor, and host of the WebJoy Podcast.

[00:00:20] EH: You know, in my mind, when I think about documentation, I think about explaining how things function and explaining how you engage with it.

[00:00:29] SY: Eddie talks about what documentation means in the context of development, why good documentation is so important, and how gaining good documentation skills early on can give you an edge in your career after this.

[MUSIC BREAK]

[00:00:54] SY: Thanks for being here.

[00:00:55] EH: It’s my pleasure. Thanks for having me on.

[00:00:57] SY: So Eddie, you have a very robust resume of a bunch of different software engineering roles at different companies and you’ve been the lead front-end software engineer at Glassdoor for the past year. Tell us where your coding journey began.

[00:01:12] EH: So I actually got into coding when I was pretty young. I’m actually pretty much all self-taught. And I really got into coding because I was on a message board with some friends and the company that was maintaining it got tired of that expense. And so they said, “Hey, we’re shutting down these message boards. And so we needed somewhere to go to talk online.” And so I realized, “Well, the only way we could do that is if like I set up a place for us to go.” So I kind of said, “Hey, let me figure out this web stuff,” and I’d put up random HTML pages, but nothing interactive, nothing major.

[00:01:54] SY: Very cool. How was that process for you? How did you learn to just host a forum and figure out the server component and that sort of thing?

[00:02:02] EH: It was a lot of reading, a lot of experimenting, a lot of steering at white screens because we used PHP. And PHP, when something went wrong, it would just give you a white screen of death. And so you saw a lot of white screens knowing you did something wrong and now you have to figure out what went wrong.

[00:02:23] SY: And how long did it take you to spin up the new forum and then get it all established and set up?

[00:02:28] EH: It took a couple weeks of off and on time. I was actually homeschooled.

[00:02:33] SY: Oh, cool!

[00:02:33] EH: This was like in my junior and senior year of high school. So I had a little bit of extra time. Right? Like I wasn’t stuck in a chair all day long. So we used some of that time to set up the message boards over a course of a couple weeks. And then, yeah, we used it for a couple years after that.

[00:02:48] SY: And how did that experience lead to you being a developer today?

[00:02:52] EH: I think one thing that was really enjoyable was I just found I got more and more control over things. I mean, when I started, I just downloaded some plugins, installed them in the forum software and that was it. But then I realized, “Well, we want to do this or that.” And none of the plugins did that for us. And so what I would do is I would go in and make changes, and magically, the forum could do new things. It did exactly what I wanted it to do. And I just got this amazing level of control of the experience and that’s kind of what hooked me and drew me in.

[00:03:26] SY: And so with that interest, where did you go from there? Did you end up studying computer science in college or what happened next?

[00:03:34] EH: So about the same time I started doing online freelancing in between like kind of graduating high school and starting college. And then, yeah, I started college going for computer science. It was interesting because since I started freelancing at the same time, I kind of ended up with this parallel journey where I did online freelancing, I did in-person freelancing, and I was doing all of this computer stuff on the side where I was learning separate skills. And I was also in college trying to go down and take all the classes I needed to take for my degree. And I actually found that I started learning more in this kind of sidetrack of learning to produce websites for people than I was actually learning in college. So I actually ended up dropping out.

[00:04:25] SY: Whoa! How did your folks feel about that?

[00:04:28] EH: They were glad to be paying less money.

[00:04:34] SY: Okay. That’s great. That’s a great way to look at it.

[00:04:38] EH: They may have been a little bit upset about the amount of money they had already spent. That kind of was no longer going anywhere.

[00:04:44] SY: So what was the plan for you when you decided, “You know, I’m learning more doing my own thing than I am in these classrooms”? How are you thinking about building a career and kind of doing this in the long term? How did you think about that? And how’d that work out?

[00:04:59] EH: It was funny. Around that time, I was working at Apple Retail Stores. I was working at the Genius Bar. And I kind of had this idea, like, “Hey, maybe I can like shift from Apple Retail to Apple Corporate.” Spoiler alert, that did not happen.

[00:05:14] SY: Okay.

[00:05:15] EH: But from there, I just worked that a while and then realized I just need to start applying to jobs and use the experience I have. In that kind of freelancing space, I had done a lot of freelancing and had worked with a couple startups that hadn’t gone anywhere. But I realized I kind of had enough stuff to kind of flush out a resume. And so I thought, “Let me just put together something where I can tell the story of my journey in a resume and see if I can get a job. And it took a little while. I think I was on the market for probably seven months and actually had to move across the country. I moved back in with my parents for a little while, but I did end up getting a job.

[00:05:58] SY: And how did you frame your story? Especially nowadays, I think that it is more common, more generally accepted to not have a computer science degree or not have a degree at all, especially with the rise of bootcamps, certifications. There are so many different entry points. And so I’m wondering when you decided to drop out and you're building your resume, what was the climate like and how were you able to pitch yourself as an exciting candidate without that formal training?

[00:06:27] EH: That was a challenge for me because it wasn’t as commonly accepted to not have a degree at that time. It was about 2011. And what I ended up doing was I really leaned on these startups that, I mean, paid me no money. Well, they paid me a little bit of money, but nothing major.

[00:06:48] SY: Yeah.

[00:06:49] EH: They didn’t become anything. I mean, they closed up shop, but I had worked with them for a period of time, I think two years with one, one year with another. And I was the only technical person with that startup. And so I was able to really show all the various technical skills that I had. And that was really the framing I leaned on was kind of an independent freelancer plus working on several startups. And to be honest, a lot of places turned me down. I was trying for stuff in California. I was trying for stuff in New York because, of course, there wasn’t much that you could do remotely back in 2011. And so I was trying those big tech areas and I didn’t really hear back from any of those places, but I ended up being in the Washington DC area and I was able to get a government contracting gig. And I think part of it was just finding a company that said, “Hey, listen, as long as we can find someone who does the job, they have a contract that they had pressure, that they had to do or they weren’t getting money from the government.” And so finding a company that needed me kind of more than I needed them I think was what really helped me.

[00:08:05] SY: And tell us about your career trajectory from then. How did you end up from that first job to being a front-end engineer at Glassdoor today?

[00:08:15] EH: What happened was with each job, I kind of explored new territories. So that job was a geospatial engineer, and I really got a lot of experience with the front-end and working strictly in JavaScript as opposed to doing more full stack work in PHP like I had done previously. And so with that, I got another job with a design agency and that was all front-end work pretty much. It was using Angular framework that had been released. The original Angular one, AngularJS, and I was kind of able to learn from that. So I think it’s been interesting. A lot of each of the job changes have been a lot of learning, which has been a lot over the last decade, but it’s shown a lot of career growth. For each job I apply to, they look back and they’re like, “Oh, he hasn’t done the same thing for the last three years.” Like, “He’s had a lot of different experiences. He’s done a lot of different things.” And I think that has really helped continue the growth because they see all these changes and all these different experiences.

[00:09:26] SY: So tell me a little bit more about your role at Glassdoor today. What do you work on? What kinds of things are you building, developing that sort of stuff?

[00:09:35] EH: Yeah. I came on board as a lead front-end engineer working in the B2B org. So we work on kind of an area that most people don’t see on Glassdoor. Right? Most people know that you go on Glassdoor, you put in a review, some salary info and you get to look at how you kind of stack up against the market, but we also have an interface for businesses. And really what that allows them to do is get some kind of feeling on how people feel about their company. Right? So everyone’s leaving reviews. What do those reviews tell you as a business matters to you? Right? Are people upset at your leadership? Are they upset at your work-life balance? By analyzing all these reviews that are coming in about your company, we’re able to give really informative feedback to the business with keeping everything anonymous to say, “Hey, listen, a lot of people are finding these are the problems with your company. So if you want to turn around your perception, this is the area you need to target.”

[00:10:38] SY: Interesting. So that sounds like it’s maybe some machine learning, some AI. Is that fair to say?

[00:10:45] EH: We definitely have a lot of machine learning and AI going on in the background. Right? Particularly sentiment analysis and everything.

[00:10:51] SY: Right. Right. Yeah.

[00:10:52] EH: And then I work with the front end team. So I don’t actually get to do a lot of that fun, but they’ve made some amazing APIs we get to hit then we get to make some fun UIs that use that data.

[MUSIC BREAK]

[00:11:23] SY: So I want to dive into documentation now, which I know you are a very big advocate for, and documentation, I think is one of those things that maybe doesn’t feel like a skill, the way that like front-end coding feels like a skill, right? Or data science feels like a skill. So tell us a little bit about what you mean by documentation in the context of coding and in terms of it being a thing to be good at. What does it mean to you and how should we understand it?

[00:11:53] EH: You know, in my mind, when I think about documentation, I think about explaining how things function and explaining how you engage with it. And so that really means that there are several layers of documentation. I think the first thing that probably pops in people’s minds is like, “Oh, API documentation.” Right?

[00:12:12] SY: Right. Right.

[00:12:13] EH: It’s something that you would do publicly. Maybe for another group of people, they’re thinking of, “Oh, code comments.” Right? The thing that everyone loves, adding comments to your code.

[00:12:22] SY: Yup.

[00:12:23] EH: But for me, I really think the first thing is this idea, right, that your code should be self-documenting. So how clear is your code? Right? What are the variable names like? I think for the second step of that is how complex is your code? A lot of times when I’m looking at pull requests and I see a bunch of complex code that one of my coworkers write, I’m looking at it and I’m trying to figure out what it does. And when I have to spend more than a couple seconds trying to figure out what this does and maybe trace a couple of variables, that gives me a hint that this should probably have been pulled out into a function with a nice descriptive name. And so that’s one thing I really rely on is like using functions, not just for, of course functions, work to allow you to move functionality from different areas of your app. But even if it’s only called one time. It’s worth making something to function just for the clarity that someone doesn’t have to understand what these 10 complex lines of code do. But instead, they can read a single line that says, “Show the user’s initials.” And that’s super clear.

[00:13:35] SY: Yeah. I think documentation and specifically in the context of making your code very clear is an interesting problem because I’m a Ruby developer and I know that we tend to pride ourselves on not using a lot of comments on using really descriptive names for our methods and our variables and using that as our primary documentation system, I guess. But depending on what you’re building, how advanced, how complex, you may not be able to always get away with that, right? Like there are certain situations where comments are actually valuable where you need just a little bit more, even if it’s a comment that’s maybe more of a friendly reminder to your future self at times. And so when we think about the different ways we can document, whether it’s, as you mentioned, kind of API documentation, the style we’re probably most familiar with as users to comments, to just writing really effective descriptive code itself. How do you think about the different ways we can implement documentation and kind of when do we use what tool for what purpose?

[00:14:47] EH: The biggest question is, “Who is your user for any particular thing?”

[00:14:52] SY: Fair. Yeah. Yeah.

[00:14:53] EH: So if it is only fellow developers who are editing the code, then that’s a great use for like code comments because someone’s going to be in this code file editing this code. if you have someone who needs to understand something, but they may not be in the actual source files, right? Oh, they need to be able to deploy something or they need to change something in environment variables or they need to interface with an API. That’s when you want to create separate actual documentation, like a website documentation type thing, where people can actually access it and read it just by visiting a URL, rather than opening a specific file and code. I think one of the important things about code comments is when people write code comments, they oftentimes approach the goal of telling what the code does. But again, if you’re thinking about who the user of that code is going to be, it’s someone who’s changing the code. And so likely when they’re looking at it, they already understand what it does. What they’re missing is why it does what it does. Right?

[00:16:05] SY: Ah, interesting! Yeah. Yeah.

[00:16:07] EH: Maybe you’re pulling out an index from an array, but maybe you’re saying minus one or plus one, that number in the index. And suddenly, the next person looking at this code, when they need to change it, they aren’t quite sure why that index is being altered.

[00:16:25] SY: Yeah. That’s such a great point. I feel like anytime I have deleted code and regretted it, it is because I thought I understood why it was there. And I thought I knew better.

[00:16:41] EH: Exactly.

[00:16:42] SY: And thought, “What? This doesn’t make any sense. This is silly. I don’t need this.” And then everything crashes and burns. So that’s actually a really good point. It’s not just about what it is doing, which hopefully if you’re familiar with the code base, you can most likely figure it out. But the important part is why it is there and what purpose it has, which a lot of times, especially if we’re new to that code base or if we’re just getting put on that project is not always obvious, is not always clear. And a lot of times the developer who wrote it may not be available in that moment to explain it to us. So the why is very important. That’s a really great point.

[00:17:18] EH: Absolutely. Especially if you think back kind of this past year and kind of the great migration that everyone has been changing companies and jumping job to job. And what you end up with is companies all over the place who have lost half the people on their teams and you’ve got new people coming in and they don’t understand how or why the code works the way it does. And I think this past year, especially has been a real highlight as to when you don’t properly document these systems and processes, as well as the code itself, you end up having to take a lot more time as a company to have people spin up.

[00:17:59] SY: So what makes good documentation and what makes bad documentation?

[00:18:03] EH: I mean, I think when it comes to looking at bad documentation, it’s explaining things that people may already know. Right? It may be explaining things in a way that isn’t applicable to the person reading it. So you’re documenting for another developer. What is that developer likely to know, right? If you’re a back-end developer and you are writing API documentation, but you explain it in a way a back-end developer would understand it, then the front-end developers, when reading that, are going to have a hard time. So understanding who your audience for this documentation is for is definitely a key aspect. Whereas, if you are a front-end developer and you’re writing some code comments inside of your code. Like for example, we do a lot of destructuring of objects. So you take an object with five keys. You turn into five variables. At Glassdoor, in the front-end side, well, I can expect that anyone working on front-end in Glassdoor has probably been exposed to destructuring objects because we do it everywhere. So I don’t need to explain why I’m destructuring this thing, right? That’s kind of a common pattern that anyone who looks at the code will have already understood. They’ll probably have gotten an explanation during onboarding or when working with a peer or something.

[00:19:28] SY: So can you think of an example of some documentation that you wrote that you are particularly proud of and that you think was a good example of that documentation and how you approached it?

[00:19:39] EH: One of the biggest areas for commenting that I’ve done recently is in an area where we are developing a Node.js server. And obviously, we have different environments that the code runs in. Right? You have your dev environment, you have your QA, staging, production. And so some of the code that relies on what servers we need to hit and what things need to happen within certain environments can get a little bit complex. In fact, because of the way our servers work, we use a bunch of microservices. And so we don’t have everything locally that you would have up on the server. And so when we are running locally, we have to do certain shortcuts, like do a proxy through our local server to then hit the server up in QA rather than just hitting the server itself. And so I had to do a lot of like if-then statements that were doing things based around is the environment dev, is the environment QA, and kind of document, I think two things there, one like what order I put my if statements in actually helped add clarity. So I thought, “Okay, if we are hitting it from the client, meaning the server is equal to false, like that was one case. All the other cases required that the server is true.” And so I just had like an if statement at the beginning there, and I’m like, “Hey, if server is equal to false, then do this thing.” And if not, let it keep going. And so kind of that short circuit method allowed me to write code that looked a lot cleaner. And it made a lot more sense. As the person read down, they knew as long as I keep going, all the things that happened above are true. And so it kind of built the mental model as you read the function. And then some areas just still weren’t super clear. And so adding in some code comments, for example, explaining the fact that server is equal to false means we have to proxy the request. That wasn’t clear in the code that you were reading. And so I added a code comment there to say, “Hey, if we’re hitting this, it’s because we need to proxy this request.” And then we’re like, “If not, then we’re going to use normal hosts.” That way, someone doesn’t actually have to read two different files, maybe three different files to understand everything that was happening. They just get everything in that one line and they understand the context and all the code around it suddenly makes more sense.

[00:22:21] SY: So when you think about new developers, early career developers and trying to develop these good documentation skills, these good habits, what are some things that they can do to strengthen that, that skillset, and do that well on the job?

[00:22:38] EH: I think there’s a couple things to do. Right? The first thing is you get better at things by doing it.

[00:22:44] SY: Yep, absolutely.

[00:22:44] EG: So the more that you actually flex that muscle and the more that you add in the code comments or document different processes. For example, one thing that could be really helpful for a new hire is you are onboarded to the company and you’re going to probably be reading through the existing onboarding or things like that and there’s going to be missing pieces of information. There’s going to be something that doesn’t work. You have to reach out to someone and say, “Hey, what do I need to do here?” When you find out what you need to do, try to rewrite that documentation. If it’s not in no way that’s accessible, just like do it in a Google Doc or a Microsoft Word doc or something and send it to the appropriate party, whoever maintains the documentation. But flexing that muscle of trying to actually say, “Okay, this is pretty clear. Here’s something that says to do this. It’s not exactly accurate. Let me add or modify that.” Really allows you to kind of work that out and get some practice.

[00:23:48] SY: And having good documentation skills is obviously important, no matter where you are in your career. But I’m wondering, do you feel that there is any particular advantage to early career developers, people who are just getting started on their journey, being good at that, at that skill?

[00:24:05] EH: I think that it leaves a really good impression with teams and employers when you take initiative because so few people really spend enough time focusing on documentation that when you take that extra time and you do, it’s going to leave an impression. And that is huge because getting recommendations on LinkedIn or if people call for references or however those references go about, those kind of social… from people who you’ve worked with is one of the most powerful things for getting new jobs in the future, because anyone can write a resume, anyone can practice so that they can do really well on interviews. But when someone else says this person is great at what they do, that is, for me, one of the strongest things because that is someone else validating you. Everything else is you saying what you can do, but references, recommendations are other people saying, “We’ve seen this person do this.”

[00:25:15] SY: Coming up next, Eddie talks about the negative feelings many developers have around documentation, why they might begrudge the task and whether he was always a fan of doing documentation himself after this.

[MUSIC BREAK]

[00:25:39] SY: So I know that a lot of developers have a very negative view of documentation. Unfortunately, it’s kind of like, “Ah, I got to do this thing. I don’t want to do.” Why is there so much reluctance, a little bit of animosity maybe towards documentation? Where does that come from?

[00:25:57] EH: I think a lot of it comes from the fact that it’s two things. One, I don’t think that we’re really trained for it. We take all this time to learn coding and suddenly someone wants us to write stuff and we don’t really know how to write it clearly. And so it’s frustrating and it’s a hurdle that we just have to get over because someone’s trying to make us do something. And so I think one of the most important things there is maybe take a technical writing course, read a technical writing book, or any other resources online. I’m sure there’s tons of blog posts out there talking about technical writing. Just find resources to kind of up your game, because if you feel more confident in it, it’s not going to be as scary.

[00:26:45] SY: That is fair. And I could definitely hear, and I have heard people say like, “I’m here to code. I’m not here to write about the code.” It feels like almost an entirely separate skillset set. It’s almost a separate task altogether compared to what you’re there to do and what you’re most excited about. And I’m curious, as a developer of many years yourself, did you once feel this way about documentation? Have you always had a very pro documentation attitude or is this kind of something that you grew into and valued over time?

[00:27:19] EH: I will say I’ve definitely valued documentation more. The longer I’ve been in tech and the, I guess, higher up in the “food chain” I’ve gotten in tech.

[00:27:30] SY: Fair.

[00:27:30] EH: You know, as you become like an engineering manager and things like that, which I was an engineering manager at my last company, I’m currently an IC at Glassdoor, but when you get into those fears, you suddenly realize how valuable documentation becomes. And so it’s definitely something I’ve had to grow into and value over the course of the years.

[00:27:59] SY: Now at the end of every episode, we ask our guests to fill in the blanks of some very important questions. Eddie, are you ready to fill in the blanks?

[00:28:05] EH: Yeah, absolutely.

[00:28:06] SY: Number one, worst advice I’ve ever received is?

[00:28:10] EH: That was to not go for a specific salary range.

[00:28:14] SY: Oh, interesting. Tell me. Yeah.

[00:28:16] EH: Yeah. Yeah. So it was a little bit to unpack there, but I was going for a specific salary range when I was trying to get one of my jobs. And I was working with a third-party recruiter who’s supposed to represent me, mind you, right? Not like the company. And he said I was asking for too much money. And so that was like really intimidating. I’m like, “Really?” I feel like I am worth this much money. I knew what I was making. I felt like I was underpaid according to the market. And so he was saying I was going for too big of a jump from my current salary. And so it was scary and it’s like, “Well, do I just listen to him?” Like, “He should know what he knows.” But ultimately, I just stuck with it and I did end up getting the salary range I was looking for.

[00:29:03] SY: Good for you.

[00:29:04] EH: Yeah. It was awesome because then, he met with me one last time and he looks at me and he goes, “I can’t believe you were able to actually achieve that.” He’s like, “I’m blown away. I didn’t think you could make that happen.” So yeah. So I think know your value.

[00:29:20] SY: Absolutely.

[00:29:21] EH: I wouldn’t be where I am if I hadn’t made that leap.

[00:29:25] SY: Number two, best advice I’ve ever received is?

[00:29:29] EH: To mark days on your calendar, that you don’t enjoy your job.

[00:29:33] SY: Whoa! I’ve never heard that one. Tell me about that.

[00:29:37] EH: So I was working with this guy and he was nearing retirement. So this was in the context of retirement, but I think it’s true for any job. He told me every day that he doesn’t enjoy his job, he crosses off that day on the calendar. And his goal is that when more than half the month has an X on it, it’s time for him to look for a new job or in his case to actually retire.

[00:30:00] SY: Wow! Oh, I love that. That is so, so interesting. I think that’s such a great visual because I know so many people who are so unhappy at their jobs and they just kind of stick around. And I don’t know if they appreciate how long they’ve been complaining for and how long they’ve been unhappy for. And that’s such a great way to kind of motivate yourself to kind of face the facts and go like, “Oh, man! It’s been months. Maybe it’s time to do something.” So I really like that. That’s really interesting.

[00:30:31] EH: And I think it kind of works the opposite way, too, in that sometimes you think, “Oh, this job is horrible,” but then you look at it and you realize it’s just some certain days of the month that you have certain meetings or something that you hate. And the rest is actually really good.

[00:30:48] SY: Number three, my first coding project was about?

[00:30:51] EH: A video game fan page for Final Fantasy.

[00:30:55] SY: Oh, cool. What’d you build it in?

[00:30:57] EH: It was actually just built using front page and just HTML. That was like back in the day. I was like 13 years old.

[00:31:06] SY: Yeah, very cool. Number four, one thing I wish I knew when I first started to code is?

[00:31:13] EH: That simple code is more important than complex code.

[00:31:17] SY: Yeah. I remember in the early days being just very impressed by complex code and now complex code makes me angry. So I feel like I’ve grown a lot.

[00:31:28] EH: Exactly. Anytime you start coding, you look at this complex code and you think, “Wow! That person’s a genius.”

[00:31:34] SY: “So cool!” Yeah. Yeah.

[00:31:36] EH: You know? Now I see it and I think what’s wrong with this person and why would they have not made this simpler?

[00:31:43] SY: Yeah. Exactly. Well, thank you so much for joining us, Eddie.

[00:31:48] EH: Absolutely. Thank you for having me on. It was a pleasure.

[00:31:57] SY: This show is produced and mixed by Levi Sharpe. You can reach out to us on Twitter at CodeNewbies or send me an email, hello@codenewbie.org. For more info on the podcast, check out www.codenewbie.org/podcast. Thanks for listening. See you next week.