[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 technical writing with Philip Kiely, an author and technical writer.

[00:00:19] PK: There’s this idea that stuck with me for a long time, the idea of a yellow belt mindset where a yellow belt is the second lowest rank in martial arts, that means that you have so much to learn, but it’s the second lowest rank. So you’ve also taken a step, and that means you have something to teach because there’s people who haven’t taken that step yet, and it’s your responsibility to help them take that step in the same way that other people helped you.

[00:00:45] SY: Philip talks about how he first got into technical writing while studying abroad in Budapest, what technical writing is, what technical content platforms are out there, and why new developers should publish content early in their careers after this.

[MUSIC BREAK]

[00:01:06] SY: Thank you so much for being here.

[00:01:07] PK: Thank you for having me.

[00:01:08] SY: Yeah. So let’s start with the beginning. Why coding? What was the interest in that?

[00:01:14] PK: So I started a computer science major in my first year of college because it’s what my friends were doing. So it’s a good thing that my friends were interested in something as awesome as computer science.

[00:01:24] SY: Yeah.

[00:01:25] PK: And not like underwater basket weaving or I might have been on a very different trajectory.

[00:01:29] SY: Right. I love that. I love that you made that decision from your associations, from your peers. Sounds like that’s kind of worked out for you.

[00:01:35] PK: Yeah. Well, what happened is I got invited to this hackathon by a couple of guys who I had just started playing D&D with. And we went to this warehouse in Ames, Iowa, in the middle of a snowstorm and sat around coding for three days and I had a great time and I haven’t really looked back since.

[00:01:53] SY: So I know that part of your education was a study abroad trip to Budapest. Can you tell me a little bit about that and what influence that had on your coding career?

[00:02:03] PK: Sure. So I just really wanted to learn how to be a better software engineer because this was early on, so I didn’t really have a lot of the skills and confidence to participate in the industry in the way that I wanted. So I picked this program in Budapest called AIT that sounded perfect because it was all about computer science classes at a liberal arts school, like the one I went to. You took maybe one or two computer science classes per semester. And in this program, I was able to take 22 credits of just computer science.

[00:02:38] SY: Wow!

[00:02:39] PK: So when I was there, I was able to pick up a lot of new disciplines. I learned all about cryptography, I learned about mobile development, and that gave me a much lot of appreciation for what was possible, and it’s also where I discovered technical writing.

[00:02:58] SY: Tell me more about that technical writing discovery. How’d that come about?

[00:03:02] PK: Sure. So there was one class that I had to take for the requirements of the program that was like a Hungarian language class. I’ll admit I wasn’t paying very much attention and I started looking around on the internet and I’m honestly not sure how I found this, but I found this business and they were in the technical mentorship business and they had this platform that they had aimed at the German market that they were bringing to the American or the English-speaking market. And I saw the copy and it kind of looked like you’d run it through Google Translate. There was a lot of stuff that wasn’t super idiomatic in it. And I sent them a cold email and I said, “Hey, I noticed the site that you’re trying to bring to this new audience, and I don’t think that right now it looks very trustworthy because of all of these mistakes. I can write pretty decently and I can understand where to put the new strings in your code. So if you just send me your GitHub, I’ll put it in there for you, and then you’ll be able to get more customer.” And they were like, “Absolutely.” They paid me $500 for that, which was mind blowing. That was so cool. That was a whole month of rent in Budapest.

[00:04:15] SY: Yeah, that is so cool. Nice.

[00:04:18] PK: Then those same people said, “Hey, we have this blog that we’re trying to use to get some more attention and get some more customers and whatnot. Would you want to write some technical tutorials for that?” And I was like, “Absolutely. I would love to.” And I realized, “Hang on. If these people are willing to pay me for this thing, maybe other people will too.” And so in that same semester, I figured out that there was this place called FloydHub that was also looking for technical content. And so I wrote for them and then I used that to build my portfolio until I could write for Smashing Magazine. And I used that to build my portfolio until I could write for anyone whose email address I could find.

[00:05:02] SY: So what was it about technical writing that kept you going? It sounds like partly it was decent pay. It’s great to have your rent covered by your writing. That’s unheard of for a lot of people. That’s amazing. But was there anything else about it that made you kind of keep coming back to it and wanting to build that portfolio and write for Smashing in all these other places?

[00:05:21] PK: Yeah. So I come from a family of writers and a lot of my friends at this college that I went to were writers or literary in some way, and so I had definitely seen firsthand how difficult it is to get started in any type of writing. I had heard all the stories and read the Stephen King on writing book where he talks about how he has this whole mail full of all of his rejection letters from when it took him dozens and dozens of times to try and get published. And I got published on my first try and my second try and my third try. And I’m not a better writer than Stephen King, but I can code. And even as a junior in college, with only two internships at random insurance companies in the Midwest under my belt, I could code well enough to do some personal projects and use the information from those projects to write articles. And unlike my peers who were trying to get published in small journals or local magazines, and oftentimes getting rejected, I realized that because of this niche that I’d chosen, I could jump right to the best publications in the industry and get published right away. And so compared to the journey as a writer, basically anywhere else, tech seemed amazing. And so I went for it. And then on the other side, as a programmer, I think I’m a pretty okay programmer, but I know a lot of programmers who are way better than I am. But most of them don’t want to wait. So just realizing that I had these two skills, either one of which I’m nowhere near the best in the world at, if I put them together, then I could actually be competitive in these top markets.

[00:07:08] SY: And what was the plan with all this technical writing? Were you planning on being a writer as a profession? Were you trying to leverage it to get into a coding job? What was kind of the plan with all this technical writing?

[00:07:21] PK: I had an internship at that point lined up for the next summer that I was really excited about. And at that point, I was pretty sure I just wanted to be a software engineer long term. But I had grown up in the industry, you could say, reading people like Patrick McKenzie and reading how they just sort of document a ton of the stuff they do and how that opened up doors five or 10 years down the road. So really I was making investments that happen to pay off immediately in terms of getting published, getting paid, and some of my earlier successes. But I just knew that if I did this work up front somehow it would pay off down the road.

[00:08:01] SY: I love that. And now you are an author and a technical writer at Baseten. What does your professional technical writing job, your full-time technical writing job, what does that look like? How does that compare to the writing you’ve done in the past?

[00:08:16] PK: What’s really cool about transitioning to full-time, and this is actually my first full-time job as a writer, I’ve had full-time jobs in other areas before, it’s the depth that you get to go into. You get to engage so deeply with just one subject. In my case, machine learning operations and how to build the best platform for startups to deploy ML models. I get to just learn about that topic over and over and over again, rather than bouncing around like I did when I was writing for different clients. And it lets you learn about how to structure content, how to maintain content. That’s been one of the biggest struggles. And how to write the same thing for multiple different audiences. So for anyone who hasn’t had a full-time job in technical content, whether that’s as a developer advocate, as a technical writer, as a developer experience engineer, as a community manager, it’s really different from even a pretty thriving freelance profession. But I really recommend trying it out because I wasn’t sure that full-time technical writing was for me, but it turns out it really is.

[00:09:33] SY: So tell me more about how you define technical writing. Because when I think of technical writing, I either think of documentation or I think of kind of blog posts, kind of these articles that say, “How to do X, Y, Z with this tool?” Is that the way you understand technical writing or how would you define it?

[00:09:52] PK: It took me a while to actually want to call myself a technical writer because the field is very broad. If you have someone who’s writing an aviation manual, they’re a technical writer. Someone who’s writing the instructions for how to operate a dishwasher, those packets that you get with any appliance that you immediately throw away, all of that is technical writing. And those people have worked very hard to establish themselves in an extremely specialized profession that is materially different from the kind of work that I do. And then there’s also sometimes a little bit of a negative association with technical writers, an idea that while the word technical is in the name, you’re not really a developer or a software engineer. A lot of times people might think a technical writer doesn’t know how to code because at some of the bigger companies, you have certain roles that, again, require like a very specialized set of skills, but not necessarily a ton of hands-on software development. So with all of that in mind, I do think that technical writer is a meaningful title in the software engineering world. But really what I focus on is a holistic approach to developer experience, and the part that I just happened to contribute to that developer experience is content in the form of documentation, tutorials, examples, sample notebooks, all that sort of stuff.

[00:11:25] SY: Yeah. I love that definition, that framing of it. One thing also that I’ve started to appreciate over the years of being in tech is that there’s technical writing, which I think for most of us, we think of as written words, right? But when we think about technical content, there’s so many different formats. There’s so many different platforms that you can use. I’ve seen like dev TikTok, coding TikTok really take off, for example. What are some of the other platforms or formats that count as technical content that may not be the more traditional, the more expected documentation style that people are thinking of?

[00:12:07] PK: It’s a really broad field, and even if you’re not a writer or you don’t think of yourself as a writer, hint, I think everyone’s a writer, you can make a great contribution to the field in a lot of different ways. So definitely video and audio are the two big formats other than just the written word. And like you said, there’s a ton of great stuff on all of the platforms, really. You have a super thriving YouTube community. You have podcasts that are dedicated to technical topics, but even within the world where I am more comfortable, which is the written word, you have a lot of different formats. One thing that I’ve been doing a lot at work recently that I wasn’t expecting to enjoy as much as I do, but I think it’s a really interesting thing to work on is making Jupyter notebooks. So making these vulnerable examples and putting them up on Google Colab and basically integrating code and words together to take the user through an interactive journey. And actually this is kind of awesome because it saves some of the really boring parts of a lot of tutorials where you try to spend a few hundred words explaining to the user exactly how they should set up their environment so it’s the same as yours. They have the same environment to work in right out of the gate. And then you just run down these examples and you’re able to, instead of putting screenshots or code blocks or whatever, you are able to just fully integrate the code and the words. I guess I should also mention there’s a lot of visual media in technical content. So if you can make any kind of zine or cartoon or infographic or visualization, some people are very textual learners, some people are very visual learners, so you’re going to reach a whole new audience with the same ideas if you can put it in these different formats.

[MUSIC BREAK]

[00:14:22] SY: At what point in a developer’s career journey, assuming they don’t have plans to become a professional technical writer or technical content producer, when do you feel like it makes sense to start creating some of their own technical content?

[00:14:38] PK: I think you should start as soon as possible, and that’s because of it working kind of like compound interest. So if you start writing early, then all of that early work compounds with your later work, it gives you some longevity, it gives you a sense of progression, and sometimes stuff that you made as kind of a throwaway project early on sticks around. I have a couple pages on my website, my personal website. One is this project that I did sophomore year that’s like an incredibly terrible poetry generator and one is this random article I wrote a few years ago about how to use Python’s Watchdog library because I was running into some bugs and I needed a way to write down what works so I could reference it later. And those two pages combined for like thousands and thousands of click-throughs of Google search per month. And they’re just random throwaway things that I wrote a long time ago. So you can get those kind of early wins and get momentum. And also, if you have this stuff in your portfolio early on, it really helps you stand out because no one else is doing it. No one else has, especially if you can get published in these certain well-known publications, which is again like way easier than you think it would be, it’s kind of like having a book on your resume or something like having published a book with a publisher, but with one one-hundredth the investment of time.

[00:16:07] SY: So what is the benefit of creating technical content, assuming you don’t plan on being a professional technical writer? Why would I do it to begin with?

[00:16:18] PK: So it starts by benefiting yourself because I tend to think that the best way to learn something is to teach it. And that comes from martial arts actually. I’ve been doing martial arts since I was five.

[00:16:30] SY: Oh, wow!

[00:16:31] PK: And in martial arts, everyone’s constantly learning and teaching. And I often find that if I’m struggling to understand how to do a certain technique properly, sometimes if I explain it to someone else, that’s what helps me understand it. And then sometimes I think I understand something and I go to explain it to someone else. Like, “Hey, buddy, watch this,” and then it doesn’t work. So it’s a great way to improve and test your skills and knowledge when you want to teach someone. And I think that it can be really intimidating to do that early on. I know that in martial arts it’s really intimidating to try to show someone something, especially if that person is more experienced than you, which is very explicitly shown in martial arts. Right? You have different colored belts to say who’s better. But I think that there’s this idea that stuck with me for a long time, which my professors, which is what jiu-jitsu calls coaches or my sensei, which is what other martial arts call it, explained, which is the idea of a yellow belt mindset where a yellow belt is the second lowest rank in martial arts, and that means that you have so much to learn, but it’s the second lowest rank. So you’ve also taken a step, and that means you have something to teach because there’s people who haven’t taken that step yet and it’s your responsibility to help them take that step in the same way that other people helped you.

[00:18:02] SY: I love that yellow belt mindset. I think that’s brilliant. So let’s say that we are convinced we are ready to start creating this technical content, get into some of this technical writing. I imagine the first thing to do is to figure out what in the world we should write about. How do we come up with topics? How do we come up with something to say?

[00:18:22] PK: So this is a problem that all creators face.

[00:18:26] SY: Right.

[00:18:26] PK: Right? If you are a vlogger and you make videos about your life, then you have to do interesting stuff in your life so that you can make videos about it. And technical content is honestly the same way a little bit. It’s more like vlogging than you might imagine because the thing that makes great technical content really stick is that it has some authority behind it. It has some presence and that you’re saying, “Hey, I did this thing. It worked for me. Here’s how it can work for you.”-[00:18:56] SY: Right.

[00:18:56] PK: You have to do it for real before you can write about it.

[00:18:58] SY: Right.

[00:18:59] PK: And so the first place to look is just your own experience and you don’t honestly need much. One project, one school assignment, one thing you worked on at your job, although do be careful about writing about things at work because there can be intellectual property or trade secret issues there. But basically anything that you learned recently, unless you learned it from a single source, front to end, and you understood it exactly the same way that source understands it, then you have some unique perspective to offer on this topic. And you can write about it and you can compile different sources that you used or you can explain the one direction that you followed, but you did it from a different approach or a different mindset. So really, you just have to think carefully about the work you’ve been doing recently, and you’re going to find things to write about.

[00:19:55] SY: Nice. Now the big question is, after we have our topics, I think that there’s still this fear of hitting publish. There’s still this, if you want to call it imposter syndrome, you want to call it just good old-fashioned nerves, we are scared to put ourselves out there. How do we get past that fear and click on that publish button?

[00:20:19] PK: So there’s a few different ways of doing this. I think the best way is to have an editor. And if you are working with a publication, they’re going to have someone edit that piece for you and you are outsourcing the decision to them about whether or not it’s good enough to publish. And so having that external authority can really help you out. Or even just having one of your friends just be able to read your piece and say, “Hey, yeah, this is good. You should put this up.” Or, “I find this a little confusing. Here’s some things you can work on to make it a little better.” Having just that one point of confirmation can oftentimes be enough to get over that. If it’s a broader or deeper feel of publishing, a feel of putting yourself out there, then there’s a lot of different things that you could do to try to work around that. One thing is a lot of people in tech publish under a pseudonym or a partial pseudonym where you’re not attaching your real name to the content, which has its pros and cons. If you’re not attaching your name to it, it’s hard to get all those career benefits we were talking about earlier, but it can also make it a little bit more comfortable to publish, especially if you’re someone who’s underrepresented in tech and maybe not comfortable with some of the negative reception that unfortunately can happen to like viral pieces. A lot of times a pseudonym can help with both psychological and wheel safety. But another thing that you can do is publish under like a brand, basically. That’s a little different because if I were to wait for the New York Times, I’m attaching myself to that credibility and they’re staking their credibility on my piece.

[00:22:01] SY: Right.

[00:22:02] PK: So there are even simple brands like towards Data Science, Dev.to, Hashnode have these different like publications on them, basically, that will syndicate your content. And again, that’s getting you that external validation.

[00:22:17] SY: Absolutely.

[00:22:17] PK: And getting you past that publish button. So three different approaches there. Mix and match them. Pick the one that works best for you.

[00:22:24] SY: So there is the fear aspect, but then there’s also that voice that a lot of us feel whenever we’re creating any type of content that basically says no one cares. No one cares what I have to say. No one’s going to read it. No one’s going to look at it. It’s almost the opposite problem of what’s the point of putting this out there when no one’s going to come to my little website and read my little thoughts and my little words and kind of this minimization of our own value. How do you get around that? How do you get over that head space of feeling like what I have to say as a beginner, as someone who’s new to this just doesn’t matter?

[00:23:01] PK: Well, if it doesn’t matter, then you should just publish it. Right?

[00:23:05] SY: That’s fair. That’s true. Low stakes. Yeah.

[00:23:08] PK: Yeah, exactly. It lowers the stakes. But in that case, write stuff that’s useful for yourself. I do actually go back and read some of my old content because a lot of times I’m trying to do pretty much the same project and it’s basically like documenting your code, but in public.

[00:23:27] SY: So if I go back and look at like that Python blog post that I mentioned a few minutes ago, that gets all those click-throughs from Google, well sometimes that’s me trying to remember how to use this library because I use it in the build script for my static site generator. So there’s always the audience of yourself and if you can write things for your future self that you’ll find useful, then, sure enough, other people are going to come along and find it too.

[00:24:01] SY: Philip talks about the impact that a content portfolio can have on finding job opportunities and advice for folks looking to start technical writing after this.

[MUSIC BREAK]

[00:24:22] SY: If we get as far as publishing and hopefully publishing a few times and we’re creating our technical content online, we’re getting it out there, what is the best way that we can leverage all of these activities into a job opportunity? Because I think at the end of the day, for most of us, we’re here to get a job, we’re here to get that first developer job, get that second developer job. How do we use all this really good writing and content creation to get us to a job?

[00:24:54] PK: Yeah. It depends on exactly what you want. If you’re looking for a job in like developer relations, technical writing, any of these content heavy, but still software roles, then having this portfolio is just an essential part of your application in the same way that the education, prior work experiences, even more so, honestly. I think the entirety of the email I sent to apply for my current job, 90% of it was dedicated to content that I’d published. If you are a software developer, though, it’s a little bit more of like a bonus. It’s an extra thing that you’re using to differentiate yourself. Maybe some people have really cool side projects that they’ve worked on, really cool apps they’ve built and published. They have a really cool personal website with all these fancy JavaScript features on it. But if you have three or four pieces of content, especially if they’re published with a known publication in tech, and you list those right there on your resume or talk about them in your cover letter and link to them, then your future employer is going to click on them and read them and see not only what you’re capable of, but also how you think. Technical interviews for all the problems are allegedly supposed to not just say like, “Can you write this code,” but help the developer, help the company understand like how you think about problems and how you think about code. And most technical content is a little bit of a story. It walks you through the way you develop this solution. And so if you can show how you think through this technical content, then they’re going to be even more confident in your skills.

[00:26:36] SY: Absolutely. So what advice do you have for people who are listening to this episode, hopefully are inspired to start creating some technical content of their own. What advice do you have for folks looking to begin?

[00:26:49] PK: Yeah. So I have this free website called Who Pays Technical Writers that curate along with some other people in the community. And basically, it’s inspired by this website for the writing community because, again, I come from a more non-technical writing background, so I’m aware of this thing called Who Pays Writers, which is basically just a list of a bunch of places people have written for and how much they got paid. Pay transparency is very a big thing in writing.

[00:27:17] SY: Yeah. Yeah.

[00:27:17] PK: So who pays technical writers is the same thing, because who pays writers actually won’t let you post technical writing stuff on there and you can go on the site and there’s a hundred different places on there that are looking for people to write. And you just filter by whatever topics and interests you have and pick a couple and send some pitches. And it really is that easy. You might not get it the first time or the second time. I’m not saying that you’re going to have a hundred percent success rate right out the gate. But if you have a compelling title idea and an outline for an article that you want to read and you appropriately match it to the audience and the topic range of the place you’re applying for, then the editor’s most likely going to give you a shot and see what you can do.

[00:28:06] SY: Very cool. Now at the end of every episode, we ask our guests to fill in the blanks of some very important questions. Philip, are you ready to fill in the blanks?

[00:28:20] PK: Absolutely.

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

[00:28:24] PK: Don’t ever give up.

[00:28:25] SY: Oh, tell me about that.

[00:28:27] PK: Persistence is super important.

[00:28:29] SY: Yes.

[00:28:30] PK: But I think that sometimes you can definitely have a sunk-cost fallacy.

[00:28:37] SY: Oh, yeah.

[00:28:38] PK: And I’ve definitely had some different projects, even a couple different jobs, where I was really, really invested in it and it just wasn’t working out, and I had to walk away from it in order to find what the next thing was going to be.

[00:28:52] SY: Absolutely. Number two, best advice I’ve ever received is?

[00:28:56] PK: Definitely that yellow belt mentality I was talking about before.

[00:28:59] SY: Yeah, I love that. I love that. I think it’s great.

[00:29:02] PK: You know, it’s the solution to understanding how to both teach and learn at the same time, and it’s also really the solution to that imposter syndrome. It’s like, “Hey, I’m a learner too, but here’s what I have so far.”-[00:29:16] SY: Right. Number three, my first coding project was about?

[00:29:20] PK: It was an isometric map generator for making D&D dungeons.

[00:29:26] SY: Whoa, that sounds complicated

[00:29:29] PK: Well, I didn’t do a lot of the complicated stuff.

[00:29:31] SY: Okay.

[00:29:32] PK: It was at that hackathon that I mentioned earlier on, which by the way, I snuck into, because I was 17 at the time, and they were checking IDs at the door. You had to be 18. But anyway, the two people I was there with, we all played D&D together. And so we built this thing inspired by some drawing we saw on Reddit that would let you build these like extremely simple dungeons. It had terrible graphics. It barely worked. It had the like slowest user interface ever. It took you like 10 minutes to build anything with it, but I learned how to put a website on the internet. So…-[00:30:05] SY: There you go.

[00:30:05] PK: That’s basically all I’ve been doing ever since.

[00:30:08] SY: Very cool. Number four, one thing I wish I knew when I first started to code is?

[00:30:13] PK: The importance of the build.

[00:30:16] SY: Oh, tell me more.

[00:30:18] PK: So the build is the idea of like taking your code from a local repository and getting it into production.

[00:30:26] SY: Yes.

[00:30:27] PK: And it turns out that in a real job, it doesn’t matter how great something you make is if it just lives on your computer.

[00:30:36] SY: Yes.

[00:30:37] PK: So a lot of times, like when I first started at my current job, one of my early goals, even though I was in a low or I wasn’t really expected to ship a lot of software, was to just like get a typo fix into production. Literally like, “Can I change one word on the website? Can I change this size of this button to make it align with the others?” So super simple. One line, sometimes even one character of code, but understanding the process of getting that off of your computer and into the production system, especially at bigger companies where that system’s going to be a lot more convoluted I think is just like a massive early win to get at a new job.

[00:31:20] SY: Very nice. Well, thank you again so much for joining us, Philip.

[00:31:23] PK: Yeah, thank you for having me. This was so much fun.

[00:31:33] SY: 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.