Writing for Software Developers with Philip Kiely

Software Sessions

Philip Kiely is the author of Writing for Software Developers and has written for companies like Smashing Magazine, CSS-Tricks, and Twilio.

We discuss:

• Doing research beyond the first page of search results
• Writing e-mails people will read
• The "get it done" and "learning" modes of readers
• Making articles easily skimmable
• Long form articles vs Stack Overflow
• Promoting and launching a book
• Borrowing the reputation of others

Related Links:

• Writing for Software Developers
• Personal Site
• @philip_kiely
• Stripe documentation example (Complete code sample with switchable frontends, backends, and walkthrough as you scroll)
• Go by Example (Straightforward samples readers can copy/paste)
• Tailwind UI (Sustains Tailwind CSS open source project by providing prebuilt components)

Music by Crystal Cola: 12:30 AM / Orion

Transcript

You can help edit this transcript on GitHub.

Jeremy: [00:00:35] This episode, I'm talking to Phillip Kiely. He's the author of the book "Writing for Software Developers." We usually talk about code on this show, but knowing how to communicate with developers is just as important. We discuss topics like making articles easily skimmable and writing with a specific audience in mind as well as crafting emails that people will actually read.

We also talk about his experience creating, promoting, and launching his book. And what he learned from his many interviews with people like Cassidy Williams and Patrick McKenzie. If you want to get better at writing or you've ever considered launching a product, I think you'll enjoy this conversation with Philip.

Phillip, you recently graduated with a computer science bachelor's from Grinnell College and I'm sure you did a lot of research. When you have something new that you're trying to learn how do you get started?

Philip: [00:00:48] As a developer, I spend a lot of time getting error messages while I'm coding. The first thing I do whenever I get an error message is I just plop it into Google, see what comes up, see what people are saying on Stack Overflow, GitHub issues, that sort of stuff.

I also have a background in journalism. Having worked at the Grinnell College Scarlet and Black newspaper I have a lot of experience going and just talking to people doing interviews. And that's why that felt like a very natural thing to include in the book.

It's also something I've been fortunate to do in articles. For example, I wrote an article in Smashing Magazine about remote part time teams using agile development methodologies. As part of that, I did a quick email interview with one of my professors at the time as well as a different professor who had written the book that we were using as the textbook in this class about software development.

Bringing in those outside perspectives allowed me to write an article that was so much better than anything I could come up with from my own experience. So really when you're looking for things to use in your own writing look broadly and don't just look at the first page of Google results.

Ask specific questions, whether it be of a search engine or of an experienced person in the field. And then cross check that information against each other to make sure that it all matches up and presents the information in a way that's orderly and meaningful to the reader.

Jeremy: [00:02:19] The people you're reaching out to most likely don't know you and you're asking them for advice or for an interview. How do you get these people to say yes and agree to help you out?

Philip: [00:02:31] It depends on what I'm asking for. In the case of the article that I was mentioning earlier, I was asking for maybe 5-10 minutes of their time to do a quick quoted answer to one or two very specific questions that I knew they had off the top of their head because I had just read a whole book about it and that is actually a pretty easy ask. Most people who are in the public do receive a lot of email but don't necessarily receive a ton of these sort of requests on a daily basis. And if you make yours compelling and specific they are pretty likely to respond to you.

I'm nowhere near the public profile of the people I've been reaching out to. But over the past week with this book launch, I've gotten a ton of inbound emails so it's been really interesting to consider this question from the other side. Considering which of these emails I'm taking the time to write very detailed responses to. Which ones I'm shooting back a real quick one liner. And which ones I'm just pretending I never saw and sticking it in the trash.

I think that making my emails to these people who I'm trying to get interviews from very short, very specific, very relevant to their interests. Showing that I'm not just reaching out to them because they're a big name or because I had an idle inclination but because I'm very invested in a project that I need help with.

In terms of finding interviews for the book. It was the same process just magnified because instead of asking for a quick email exchange, I'm asking for 30-60 minutes of their time. I'm asking to ask them some really tough questions about their work and have them think through it and give answers that are going to get published and have a bunch of people read them.

I'm also implicitly asking them to endorse the work that I'm doing and the product itself with their presence in it. I have the picture of everyone who I interviewed on the sales page, for example. And with that the pitch is a little different. It's about investing credibility. The people who I interviewed for this book were kind enough to invest some of their credibility in this project and if the book was total garbage they would have gotten a negative return on that investment and future projects that they're involved with.

On the other hand, if I put in a lot of work editing and producing a great book then they're going to get a positive return on investment and to some small degree be even more credible for their involvement with this project.

I never state that explicitly, but throughout the process both the first short cold email, the scheduling, the interview itself, and then keeping them up to date on the progress of the project after the interview... I just have to deliver to them professional correspondence that gives them confidence that this project is going to have a positive return on the credibility that they invest in it.

Regarding the interview itself... I want to make sure that I'm asking them questions that people haven't asked them before or at least asking them these questions in new ways that allow them to say new things that they haven't said publicly in the past. Both because it's more interesting for them and it allows me to create a better product in doing so.

I'm going to inform them that I've read their work and not just by saying, "Hey, I've read your books" or "I've read your articles", "I've listened to your podcast". I'm going to say something specific that I liked about a previous thing that they've done. Or I'm going to reference that I just interviewed someone for the book that they know from a previous interaction. By establishing that credibility and proof that I'm going to be very invested in the project I can make them more likely to respond.

The final thing is that it really is a volume game as well. I sent almost a hundred pitches to the sort of people who you would expect to see on the list next to the 11 who did say yes. A number of people were just too busy to respond, have a policy against doing interviews or for any number of reasons didn't want to appear in the book, and that's totally fine that's their prerogative.

What I would encourage people to say is, okay, if I need 10 interviews for the thing that I'm trying to do I'm going to send a hundred emails. If I'm writing an article and I only need one or two interviews I'm going to send 10 emails. If you get more interviews than you're looking for, that's great. I was only planning on putting eight in this book and I got 11. And they all add a ton to the product. It takes a lot of time because you are sending specific targeted emails at scale but it was also worth it.

Jeremy: [00:07:18] So basically when you want to talk to someone... do your research, read their work, learn a little bit about their background and show them that in your email so it'll be more personal and it will make it clear that you're not just shooting emails out to everybody and hoping for a response.

Philip: [00:07:32] Then the other approach that you can take is more of the approach that I used pitching you to come on this show. I think I wrote you about a three sentence email and the first sentence was: "Hey, I just graduated from college and made $20,000 selling a book." The second sentence was: "I'm doing a podcast book tour." The third sentence was: here's how you can contact me.

When you're doing cold email like that it's almost like a non-negative form of clickbait. You're trying to intrigue the person who you're reaching out to say: Hey, I'm going to give you some information that might be interesting to you given what I know about your background. I'm going to include links so that you can verify that I'm not some scammer. Then here is the exact actionable steps that you can take with this information if you're interested.

Jeremy: [00:08:22] It was very straightforward. Then if you click the link, you see the landing page and see all the people that you interviewed whether that's Patrick McKenzie of Stripe or Cassidy Williams from Netlify. And I think anybody who sees that landing page and sees all the people that you interviewed it'll probably make them think there's something to the book so there's two different strategies for getting someone to notice your email.

Philip: [00:08:45] Right. You don't need that. I didn't have any of the social proof when I was getting the people who I was interviewing to interview with me. But if you have it you should definitely use it cause it makes it way easier.

Jeremy: [00:08:58] And when I received your email, I previously saw the post on Hacker News about your book. It was really easy to make that connection because I saw the same title in your email and I didn't have to think too hard about it.

Philip: [00:09:13] All credit for this title goes to my mother. I wanted to call this book the "Technical Content Development Handbook" and "Writing for Software Developers" is a much better title because it more accurately describes what the book is about, who the audience is, how they're going to use it. But also when you're sending cold email like this, every single bit of this very, very short email counts a lot. Having every aspect of your product optimized for people can understand this quickly is really helpful when you're sending cold email.

Jeremy: [00:09:45] You had an interview with Cassidy Williams and she was saying developers don't like being sold to. I think developers like in a broader sense knowing the specifics of what they're getting.

They want that title that says this is what this book is about. So that was a smart move.

Philip: [00:10:07] Yeah. Her interview definitely influenced how I created the sales page for this book by highlighting the interviews that I did, providing a free sample chapter, answering a bunch of made up questions in my frequently asked questions section. All of that was designed to do exactly the same thing that I do when I'm writing articles for clients that then use them for content marketing. I'm just providing a bunch of information and trusting that the people in my target audience are smart and engaged and want to find valuable things on the internet and that all I have to do to make the sale is provide them with the information they need to make their own decisions.

Jeremy: [00:10:49] Now that you're on the other end looking at inbound emails, what gets you to click versus just keep scrolling?

Philip: [00:10:59] It's a little difficult because there are so many different things that can make me interested. I'm still new to this so every email I receive is in some way incredibly exciting. Check back in 10 years and see if that's still the case. But I think that having confident well written emails about just about anything will pique my interest as long as someone demonstrates that they've put a bit of thought and effort into the communication. I feel somewhat of an obligation to respond with an equal amount of thought and effort.

Jeremy: [00:11:35] Instead of emails, how about when you are researching something. You're trying to learn how to do something and you see the list of tutorials on Google. Do you have a heuristic or something that you look at to decide this one doesn't look good I'm going to keep scrolling?

Philip: [00:11:50] Absolutely. And it depends on why I'm doing research. If I am programming myself and I want to solve an issue like I was talking about at the beginning of this episode I'm just going to be clicking through things as fast as I can, looking for code samples and trying it and seeing what works.

On the other hand, when I'm trying to learn a new skill or get some general background knowledge because I'm about to write about a topic, I do a much more methodical approach where first I click through the first few results, find something, read it, and then I read all of the things that article references. And then I read all of the things that those articles reference. It's more of a depth first search than a breadth first search.

And by doing that, I rely on the efforts that other authors have made to curate good information in the text or a further reading or sources section at the end. And I make the conscious effort to do the same thing in my own writing including in most articles some combination of in text citations or a list of further reading at the end that both talks about the exact topics that I used in the article and maybe includes all of the sources that I've cited as well as interesting things in tangential topics that might not have made it into the article proper, but are going to be really useful to someone embarking in a similar journey trying to figure out a topic.

Jeremy: [00:13:22] There's two very different modes of research. You're saying one is I am working on a problem right now and I want to know how to solve it. And for that you're basically scrolling through and looking for code samples that you can copy and paste.

And the other would be trying to get some kind of deeper knowledge and the way you search through things is very different. I think it's interesting to think about it that way.

Philip: [00:13:50] It is and it's very important to think about your audience's mode when you're writing. A lot of people talk about picking an audience, finding and defining exactly who you want to write for, and figuring out things like: How much programming experience does my potential reader have?

Those questions are very, very important and can be difficult to address because as a writer you get to define your own audience. You write for someone with a specific background and that person comes and finds your work if you do a good job of distributing it. And people without that background might come across it but don't read it.

However when you're thinking about your audience's mode that is something that you have even more control over because you can write the exact same topic with the exact same background two very different ways depending on whether or not you're trying to get someone to sit down, work through an entire sample application with you, and really develop a broad and deep understanding of a particular topic.

Or you're just trying to get someone in and out and get them a code sample and get them a quick explanation of why they might be experiencing an error and what they can do in the future to resolve it and then get them back to their work.

I think great publishers understand this difference and they're going to hire people to write technical content or they're going to write technical content themselves with an eye towards intentionally creating both types of content and trying to avoid hanging out in the middle where they have an article that's difficult to parse and doesn't provide sufficient depth.

Jeremy: [00:15:28] When I'm looking for a specific code sample a lot of times I'll look for links that are to Stack Overflow because I know that if I go to Stack Overflow then it's going to be the short code snippet and I'm not going to have extra time trying to find the thing that I'm looking for.

How do you decide whether to go to Stack Overflow vs click on a long blog post?

Philip: [00:15:56] Stack Overflow is an incredibly important part of the technical content ecosystem online. When I think about my competitors I don't think about the people who I'm competing against to maybe write an article for a client or land on the front page of hacker news every day.

I'm competing against the vast amount of free technical content already available on sites like Stack Overflow and what Stack Overflow is really great for is exactly this quick answer stuff that we've been talking about. But the places where I think blog posts can shine is when someone is not asking how, but instead asking why or what or who or any of these other questions.

Because if all you need is a code sample it's probably because you already know how to use it. You already know exactly what you want to do. Bringing back my original point about asking specific questions: Sometimes you don't yet have a specific question and your goal in research is not to find an answer, it's to find a better question.

And a lot of times going to longer form resources like blog posts or articles or even books is a great way of asking better questions which is a really, really critical first step in research that is easy to overlook because it might not feel like progress. It's kind of like when you're programming and you've been stuck on an error message for awhile and then you change something. And you got another error message but at least it's a new message and that's really exciting and that feels like progress. The same thing with asking a newer, better, more specific question can be achieved by consulting longer form resources first. Then you say, okay, great. I know that I just need to sort this database index by date ascending rather than descending and that's my issue. That's what's causing all these problems. I can look up the SQL query to do that on Stack Overflow.

Jeremy: [00:17:51] Yeah, that's a great point because stack overflow is not always the best place to understand why you would do something a certain way. Somebody will answer with a code snippet and if you copy and paste that, it'll probably work. But sometimes what gets lost is, is that the thing that you really should have been doing?

If you're not quite sure what you want it makes a lot of sense to have that be a long form blog post or a book or something like that.

Philip: Absolutely.

Jeremy: [00:18:23] Julia Evans creates zines, they're these illustrated guides on technical concepts. One thing she recommends is that people write for one person.

How do you decide who that person is and what's the best way to let the reader decide if they are that person you're writing for?

Philip: [00:18:45] That's a great question because once you figure that out, everything else is pretty easy. A lot of the time I write for myself in the past. I write the guide or the article or the book that I wish I had that I wish I had been able to read before starting out on a project.

But sometimes I think about, okay, I have a friend who wants to do something. I have a coworker who struggled with this. Just figuring out someone from my life who I can think about as a example of the audience. And again, that's sometimes, but not always me. That can be very helpful for solving this question and based on my interviews it's what a lot of other people do as well.

Jeremy: [00:19:29] When somebody comes to the article, do you expect them to scroll through and figure out if it's for them? Or do you think there should be a more explicit sign post saying: "Hey, for this tutorial you should probably know these things."

Philip: [00:19:44] I don't really believe in categorizing tutorials "This is a beginner tutorial" because maybe it has something really useful. And someone might overlook it if they consider themselves above that or on the flip side "This is an advanced tutorial" could scare away someone who is ready for it but just isn't confident in their work yet.

What I think of as some of the implicit markers of a tutorial first is the setting up section. When you talk the reader through here's what you're going to need to configure in your environment in order to run my sample code. If you spend a lot of time walking through the exact minutia of here's how you set up a virtual environment in Python, here's how you PIP install a package. That's going to be a really strong signal that this article is for a beginner level reader and an advanced reader can go ahead and skip that and assume that their thing is configured correctly. Move on to the thing that they're looking for and you haven't really bothered them by including that setup information as long as it isn't pages and pages of it.

On the other hand, if I was writing about a very advanced topic I might not include very substantial guidelines on how to get set up both because it's going to save some space that I'm able to instead assign to describing this complicated thing I'm talking about, but also because if someone isn't able to figure out the setup steps that I provide, then they're probably not ready for the advanced article itself.

I think that the setup section of any article provides a very important form of positive gatekeeping in terms of implicitly informing people whether or not an article is written with an audience in mind that they were part of.

Other than that, I think that like a focus on very specific titles. Not clickbait, but explaining exactly what you're doing, how you're doing it, why you're doing it, both in the title, the summary, the first couple paragraphs is a great way of letting readers know whether or not they're in the audience. And that even ties back to my own book because the title "Writing for Software Developers" lets anyone who's not a software developer know that they're probably not going to get a lot of value out of this book.

Jeremy: [00:21:59] Rather than being this gatekeeper you let the reader infer it through the title, introduction, the setup steps, and hopefully they can decide from there whether it makes sense to keep going.

Philip: [00:22:16] Exactly. The other thing about technical content in general is that it's an opportunity to provide people with a pathway into the field. People talk about how computer science is one of the easiest things to learn without going to college. I'm fortunate to have gone to a great college with very strong CS program but even still I learned a lot of the things that I use in my actual job and in my work outside of the classroom by using technical content. So I think it would be counterproductive to explicitly tell anyone: " Hey, this isn't for you."

Jeremy: [00:22:53] When you are writing an article how do you decide the scope for it? To give you an example: You mentioned you had listened to the episode with Courtland Allen. He talks about a lot of different things that are interesting.

For example: How he made his site stand out with the design, how he scaled his site, the technical stack. If you were going to write an article based on something like that, how would you decide whether to put it all in one or split it up into pieces?

Philip: [00:23:30] If I'm faced with a very large project like that, I would definitely split it up into pieces. I mean, there's so many interesting aspects of Indie Hackers. I'm sure I could write a entire article just about, the CSS within the upvote downvote buttons. You can get very, very deep and very, very specific and there's a lot of value in doing that.

On the other hand. One thing that was consistently mentioned in the interviews is that if you write a series of articles, people aren't necessarily going to read the whole series. So what I would focus on is picking out a bunch of the most interesting aspects and trying to create connected but self-contained pieces of the puzzle.

For example, this is something that I've been doing for the past few months with Smashing Magazine. Every so often I've been publishing a Django tutorial that all fit together into a broader understanding of how to use the framework. But I'll also very intentionally create it so that they are individually consumable and do not rely on any other bits of the series in order for you to get the code samples up and running in order for you to get a understanding of what the topic of the article is and what the main takeaways are.

I think I would do something very similar. I would take the smallest piece that I think will make an article, because I'm always surprised by how much bigger every topic ends up being once I started writing about it. I would find the most interesting nuggets from this massive project. I would build individually packaged tutorials around each of them. And that's where I'd start.

If you knew it was going to be a book or a video course or something that was delivered as a continuous whole, that's where I'd invest some time in talking about, okay, here is the overall structure. Here's how all of these things connect to each other, and here's how you can identify patterns in your own projects or your own work that match patterns in this example and will lead you to the specific pieces of content that I've developed that might address similar issues to the things that you're facing.

Jeremy: [00:25:43] You would default to splitting things up into as small a piece as possible while still being valuable on its own. And then if you were going to try a larger project you would have to know upfront whether that's a book or a video course.

Philip: [00:26:01] Exactly. And the thing with technical content is you have to trust your audience a lot. For example, the first half of the book is about writing a 2000 word technical tutorial for clients and I talked about this for three reasons.

The first is that writing a 2000 word article for a client is a great, achievable first challenge for people who want to get into this.

Then there was also a large amount of demand from publishers for this exact format and style of writing.

But the main reason is because this is what I have experience in but that experience transfers very easily. Everything we've talked about in this interview about finding an audience, figuring out your scope, figuring out how to make your code samples complete and runnable. All of that applies. If you're writing a book, if you're writing a README, if you're writing documentation, a Wiki, the skills are really transferable.

Similarly, when I'm writing technical content, I have to assume that the people who are reading it are smart, they're engaged, and they're going to take the specific context that I've presented them. They're going to take their own context and they're going to figure out how to bridge that gap.

Jeremy: [00:27:15] You had an interview with Chris who's a community manager at Digital Ocean and he mentioned how readers will skim code and images and they gloss over long paragraphs.

Does that match with how you navigate content or is that more specific to when you're searching for a certain type of thing?

Philip: [00:27:35] That interview had a lot of surprising things in it. And that was one of the most surprising to me because I spend a lot of my time when I'm writing focusing on crafting not necessarily sentences that my literature professors would consider to be well-executed, but at least competent English phrasing. And I spent a lot of time thinking about the readability of my paragraphs. Starting at one idea, flowing into another one, and to hear that a lot of people were skipping them was kind of disheartening. But then I did think about how I read content myself. I'm fortunate to be a really fast reader. If I'm trying to read a book with another person, it can be a little unfortunate because I'll get all the way to the end and they'll want to talk about chapter three. The way that I skim articles is I just read the text but really, really fast.

Chris had actual statistics based on using Hotjar on scotch.io to see how people were actually interacting with the site. And in aggregate, a large portion of the people were just scrolling down to the first code sample, copying it, and when I think about the mode of: I need to solve a particular issue in this application so that I can commit it and go eat lunch, then absolutely that's what I'm going to do. As a technical content writer, there are two things I can do to address that.

One is to increase the skimmability of my content as he was talking about. To maintain the same focus on good writing just put more white space in there, put more paragraph breaks, more bulleted lists, numbered lists, quick summaries. Because if those are going to be really useful to someone, I should absolutely include them. And it's going to do nothing to detract from the experience of someone who wants to really read and sit with the content.

And then the second thing is when I'm considering how to write this stuff, I do need to focus a lot more on putting in code samples that are complete, runnable, and understandable without the context of the article around them. Even if that makes those code snippets a little longer.

And it makes describing them a little more difficult because I have to parse through eight lines of code including some import statements or configuration. For the majority of the people in get it done mode who are looking at the article if that's going to help them copy it into their application more easily then that's an investment worth making.

Jeremy: [00:30:14] Let's say I'm going through a tutorial and I follow the code as it's described and if it's missing import statements or it's missing steps to install prerequisites.

That's a lot of time that's sunk. You end up googling how to complete the tutorial that you're currently working on. I can understand why that's frustrating.

Philip: [00:30:36] Exactly, and that's something that is worth investing in avoiding. One of the best examples I've ever seen of this is Mark McGranaghan's Go by Example where every single code example on that entire site you can take it, copy it, and paste it into an online go interpreter or your own go environment, hit run, and there you go. It works exactly the way it says on the site. The value of that is incredible.

One of the places we can see a real investment being made in that is with Stripe's experimental documentation that they published a couple months ago where instead of just showing people: "Here's the single function you write to integrate the payments API." They created sample applications. Not just one sample application. But the same sample application with three different backends, four different frontends, two different frameworks, all this different stuff. And you can mix and match these and download these sample applications.

And then they also did the two column design that Mark McGranaghan talked about where you have the code on the right, the words on the left and they're matched up, and you actually click through the steps in Stripe's documentation and it zooms around in the code example that you're looking for, highlighting the blocks of code that are relevant to the information that you're taking a look at.

By doing something like this, you're creating more than just a piece of technical content. You're creating an immersive experience where it's a guided walk through a complete piece of sample code and that makes it really, really easy to figure out how to bring in the thing that you need into the application that you're working on.

Or if you're not in get it done mode, you're in learning mode. Then it's really easy to take a broader look at the application and see how it's structured, see the decisions that went into it in the high level, and understand how you can structure things similarly in the future.

Jeremy: [00:32:38] It's letting the consumer of the content, the person who's looking at the tutorial decide whether all they need is the code and they understand just by looking at the code or whether they need that extra sort of guidance that's going to show up on the left side.

Philip: [00:32:53] Exactly. And making something like that is not a small investment. I don't even want to speculate how many hours of engineering time went into that. If you look at the fully loaded costs, they probably spent hundreds of thousands of dollars of engineering time on this demo. Which is worth it for them because if it gets people to integrate Stripe in the applications then Stripe's gonna make some money.

Individuals such as myself can't necessarily make a similar scale investment in technical content. I write almost exclusively about JavaScript, HTML, CSS, Python, Django, because those are the languages that I know really well and that I feel confident teaching people.

And if someone would have asked me to write a sample application in 10 different languages and frameworks I just straight up would not be able to do a good job of that. When you're an individual and thinking about how to make meaningful investments in your work. When you don't have those sort of resources, what you can do is even if you're not doing it in a bunch of different languages you can still focus in on one and you can make a really great sample application that's complete, runnable, configured out of the box. And that's going to provide a smaller niche audience of readers that same value. And then what's great is it's going to be free on the internet so someone else can come along and say, Hey, I really like this. They did a really interesting thing here. I'm going to do something similar in my framework and language of choice, and that's how great ideas and practices can propagate around the internet.

Jeremy: [00:34:31] When I'm trying to learn something, whether it's searching online or even if it's trying to do something in a company. The way that I typically learn and I think a lot of other people learn is they see an example of something somebody has done before. And that could be a sample project or it could be the way a certain feature was built in a code base at work, and just by seeing how somebody has already done it, it's not a full copy and paste, but it gives you this guide for how you can build something similar. And I think that allows people to be able to build something new a lot quicker than, just looking at API documentation.

Philip: [00:35:17] Exactly. There's no new code. We're all standing on each other's shoulders. And I think that's one of the things that's so great about technical content is even though you know a lot of it's paywalled or a lot of it you sell to publishers who release it for free with advertising or content marketing.

Ultimately we're all helping each other out to build things and it's about creating a corpus of knowledge across the entire internet that everyone benefits from.

Jeremy: [00:35:44] I'm interested to see how we can improve how we share that knowledge going forward. Is there something beyond the current tutorials we have like full featured applications or templates that people could use to learn from.

Philip: [00:36:01] I think that an under appreciated source of this knowledge is open source repositories. You can learn a lot just by going and inspecting the actual source code of big open source projects. Now, open source projects have a ton of responsibility already. The developers and maintainers and volunteers are under a massive amount of pressure to keep everything running and up to date and to continue providing new features that people are asking for often with very little funding.

So I can't just go ahead and say: "Hey, open source maintainers. You've got to add a bunch of documentation." because that's just not a realistic thing to ask for.

But I think that one under explored area that can be pretty interesting is taking a piece of open source code. And writing either as a separate thing or as a contribution to the repository directly an explanation of how it works, and I can give a anecdote about this. Well over a year ago, I was working on this application with my friend and I wanted to render an iPhone in CSS so that I could stick an image inside of it. And I found a library, an open source library that provided these beautiful CSS renderings and the one issue is that they weren't resizable. So I created my own fork of the library and wrote this Python script that used SCSS and some variables and some other things to go through and automatically convert all of these non resizable CSS devices into resizable ones. I used them and just sort of forgot about it.

A year later I decide "Hey, I want to write an article for CSS Tricks. When have I done something cool with CSS before? Oh, Hey, this time with this open source library." I pull out the code. I realize that a year ago I had no clue what I was doing and was a terrible programmer. And so I rewrite the whole thing. Which is a very common occurrence when I pull something out from the past to use in an article the first thing I do is decide it's terrible and rewrite it. But that's an important part of my own learning process and then sharing that learning with my audience. So anyway, I'm here. I have this great code. I write an article about it. And CSS Tricks is thrilled. They publish it.

What's super great is first off, this is increasing the visibility of an open source product, both the original one and then the modified version that I created.

Secondly, anyone who comes to this modified version of the product and wants to know more about it can go look at this article and read more about how it was created and thus really understand how to use it.

The third thing is that when people read technical content, as we've been talking about this whole episode, the first thing they do is they take it and they copy it and they paste it into their own applications. Whether that's personal projects, things for work, whatever. So when you're publishing technical content, the responsible thing to do is to make all of the source code open source under some very unrestrictive license. All of my clients do this. Either they'll release it themselves as open source. There'll be a disclaimer in the footer. Or what happens a lot is I create an open source thing and then I write an article based on the thing.

I sell the article to the client, but not the thing itself that's not considered part of the work product. And while this might seem like a technicality, it is an important thing to think about in terms of how you're delivering value not only to the client or to your employer, but also to the reader. Because if you're going to create something useful they've got to be able to use it. Open source can help.

Jeremy: [00:39:36] That's an interesting example of having this open source library. Having this tutorial or document that describes how it works and that helps other people learn how they can build something similar. And at the same time, you got paid by CSS tricks in this case.

So it's like everybody benefits.

Philip: [00:39:55] Exactly. It's an indirect model of promoting and funding open source software. And in this case this library is a very small scale thing. It's not something I've dedicated a ton of time to. And the original creators of the library used it as content marketing for their product.

But ultimately, I don't know if this model is scalable. I don't think you could support the development of Django by just writing a ton of tutorials about Django. But I think that at the smaller scale it is just another way that individual developers are able to monetize our own and other people's contributions to open source software in order to create useful things and pay the bills.

Jeremy: [00:40:44] Yeah. I think an interesting possibility that I don't think I've seen before is, there are some open source applications, like for example, GitLab is an open source project that's written in Ruby on Rails. I wonder if somebody could based on GitLab's code write a book or a series of articles explaining this is how we wrote a real world application in Rails. Because I think when you have a code base that is as large as their's is, telling somebody to just look at the source code can be pretty daunting.

I think there could be room to come in and walk people through parts of the source code and have something that they can learn and take to build their own projects with. I think that's a really interesting possibility.

Philip: [00:41:38] Absolutely it is. There are two great examples that I can give about the marriage of open source software, technical content, and a sustainable business model.

The first is Taylor Otwell's work with Laravel which is a PHP web development framework where he and a team have managed to not only create really great open source products, really great technical content. But also charge for various value adds that larger corporations, larger teams who are using these products are able to invest a lot in because they rely very heavily on this as a foundational part of their infrastructure and stack. Which in turn goes back to fund open source developments that make this whole product better for everyone.

Another great example is Adam Wathan's work with Tailwind UI. Tailwind is an open source CSS library that is very, very popular. It's kind of like bootstrap in my mind although I know that power users might disagree. The way that this is monetized is through something called Tailwind UI, which is a collection of components that you can buy either an individual or a team license to which was an inspiration for the team license in my own product actually.

You can buy an individual or team license. And it's I think $300 or $600 and this gives you access to a ton of components and a ton of technical content about how to use these components and Tailwind in general to make your websites look great. And if you think about it, $300 is what, three hours of developer time? Maybe less if you are hiring very experienced developers and you have fancy offices somewhere. So it's a total no brainer to purchase a piece of not just technical content, but also reusable example code that you and your development team can use to create something that looks great and drives business results.

One of the things that I drew inspiration from them as well as Daniel Vassallo's book is the idea of price discrimination with a corporate license. When you buy an ebook, it's kind of like buying a physical copy of a book. You're not supposed to email a copy of it to everyone on your team. But I figured that some companies have documentation teams or might otherwise want to purchase a copy of this for everyone working there. But I didn't want them to have to go buy a bunch of copies and so I created a team license. A new tier of the product on Gumroad. I added a one page PDF saying, here are the three ISBN numbers that you can share with as many people in your company as you want and set the price a hundred dollars higher, figuring, Hey, this is a huge markup. This is amazing. So all that work took me about 10 minutes.

So far, seven people have bought corporate licenses, which is really exciting and is a massive return on that time invested. So that's another facet of thinking about your audience during the product development cycle. How different people in different situations might use your product and then creating something that adjusts to their needs. Because for a company it's worth the hundred dollars to know that they have permission to use this book however they see fit, and to show it with as many people as they want.

Having that kind of license both helps me out because it made me all of this extra money. It also helps out the people who are buying it because it lets them use this content in a way that they might not have been able to otherwise to better achieve their goals.

Jeremy: [00:45:12] That's a great point. The threshold for what somebody thinks is expensive is very different for the person vs the company. If I look at something and it's a hundred bucks and I'm buying it for myself, it's a little expensive for me to buy. But if it's a business paying for it then it doesn't even register.

They'll put it on a card. You don't have to think about it. It makes a lot of sense to price differently depending on who's buying.

Philip: [00:45:35] Exactly. It allows me to provide the value to the people who are able to pay for it while also keeping the main product cheaper for everyone else because I'm not trying to hit a midpoint between individual and corporate use.

Ultimately what both of these examples show to me is that where a lot of the money is in technical content is first, you make something great, and then you save people time. So you've made some really great open source thing that people want to use. And then you take the businesses who can really invest in saving their teams some time and you say, Hey, I'm going to make you a great resource. It's going to cost a few hundred dollars, but it's going to increase your development velocity so much that you won't care at all. I know that both of these people have also done a lot of other stuff in technical content, written great books, built a big audience doing interesting work in public. And so I'm not sure I can attribute all of their success to this business model or even the majority of it. But I think that this business model is the sort of thing that I'm looking at very closely as I consider longer term more sustainable work in technical content development.

Jeremy: [00:46:46] Adam Wathan with Tailwind is a great example because Adam has put together screencasts, he's put together tutorials, and the quality is so incredibly high. Just going through those tutorials I learned a ton about CSS beyond just learning about Tailwind. Then you have this product that helps you move even quicker it's a very easy decision.

Philip: [00:47:11] Exactly. And this goes back to what we were quoting earlier from Cassidy Williams saying developers don't like to be sold to. We don't like to be sold to but we love to be taught interesting things. And that's why content marketing, really good content marketing does so well in the developer space. And it's actually something that gave me some pause and some doubts when I was thinking about launching my book is I was thinking I have what, 20 Twitter followers? My website gets a nice dozen hits a day. Half of them are from my friends. So I was thinking, do I have the established credibility to launch a product like this?

And are people gonna feel like I've created something that is valuable or they're going to feel like I'm selling them something? And part of that was solved using the investment of credibility for my interview subjects I was talking about earlier, but part of it was a experiment. Everyone says you have to build an audience before you launch a product. My hypothesis was, I can build an audience by launching a product.

It happened to succeed. It's a single data point. I don't know if it's repeatable. I can't guarantee it'll work for anyone else, but a lot of people might look at a business model like Adam's, and say, okay, this is great for him, but he already made however much money selling books. He already invested years and years in building this open source library. I need money now. I can't do that. But I think that an iterative approach where you build a thing, you launch a thing, you use the momentum, you build a bigger thing, you launch a bigger thing might be possible and might be a way to introduce more people to this business model and this space.

Jeremy: [00:49:02] Like you said, a lot of people do say you should build an audience first. I had a conversation with Ben Orenstein, he did a lot of public work in terms of, conference talks, blog posts, he ran a podcast for a long time, mostly in the Ruby on Rails community.

And when you ask him how did you build your audience? He said well, I was just helpful to people for a decade. And you took a very different path where you didn't have that following, but you were able to have a successful launch out the door.

And what you were saying makes sense in terms of having other people vouch for you. Having people like Patrick McKenzie, post on Twitter and say like, Hey, there's this, book, writing for developers, I think it's really great. And if you like what I post on Twitter, or you like my blog posts, I think you're really gonna like this. For me as a developer or just as a person, when I see something like that, then I'll go like, Oh yeah, I trust Patrick. I'm definitely gonna check out this book. So I clicked the link and then I get the landing page and that's the second step, right?

You get the person to the landing page, And then what's on there is attractive enough where you go to the next step, click the buy button right? So I think that social proof or having somebody else make the recommendation is pretty huge.

Philip: [00:50:24] It really is, and I will not sit here and pretend that I would have sold the number of books that I did if I didn't have the buy in from these very successful people with the interviews and the promotions.

However, there are some steps that I made that I think anyone can replicate for their own products that I'd like to talk about sort of going through the funnel.

So at the top of the funnel, like we've been talking about, it's Twitter and Hacker News, and I had no following on Twitter, but no one has any following on Hacker News. The concept of a follower doesn't exist. Every single post goes into new. So for a week I focused on, I'm going to create a great Hacker News post.

I revised it like I would revise a article for a client or even the book itself. I wrote a top level comment that I posted immediately after posting the Show HN. I looked through all data and statistics to see, okay, I'm going to want to launch this on a Tuesday, 8:00 AM central time so that people in Europe are going to be awake to see it, cause it's afternoon there. I'm going to get that East coast and Midwest morning traffic, get it to the top by the time the West coast wakes up, then they're all going to see it. And that's where I'm going to get the massive influx in traffic.

So taking the time to really consider how you present yourself on these platforms and that did rely on the fact that I've been a member and user of this platform for years, so I know it well. I know the sort of unwritten rules and what the audience is going to respond well to and not respond well.

To contrast that with Product Hunt where I posted the same thing and got 10 up votes and no views. Having an understanding of the platform that you're launching on is really, really important. And is the difference between staying at the top of Show HN for a day vs getting ignored.

That's the top of the funnel. Creating a post that really targets the specific audience of the platform that you're using. From there, my sales page, I spend a lot of time working on that. I based it on the advice from Nathan Barry's book Authority, which covers a lot of this stuff and made sure that I included not just the social proof, but also things like a free chapter so that people can look at the formatting and the content and make sure it's something that they want to read.

I focused on having a good bio listing my clients which is a form of social proof that I owned for myself over the last 15 months or so writing for people. And then with the Gumroad page itself I spent a lot of time thinking about the layout, the pricing, eventually landing on $36 as the right price because on the one hand, the book teaches a lot of valuable skills. On the other hand. A lot of the people who might be interested in reading it are going to be students like me or other early career people, which is why I also put on the website that anyone who can't afford it can just send me an email. I'll send them a copy for free. So I've sent out dozens and dozens of free copies as well.

And all of that just serves to get more Twitter followers, get more people excited about the book, spread the word. Even small things like making the book DRM free. A lot of people worry about what if someone's going to pirate my book? Well, I'm worried about exactly one thing. What if someone goes and lists it on Amazon? That's why I've registered copyright so I could issue a takedown notice. Other than that small authors such as myself have to worry about things like obscurity much more than things like piracy. I'm mostly concerned about getting the word out there about my ideas, of my content, rather than making sure that every single person who looks at the book has done so in the approved manner.

Looking at all of that, there are all of these little steps that you can consider in a launch that are going to provide a big impact on the way that your product is received. People are going to be able to perceive that you are really, really invested in this thing that you've created and you've thought through all these things, and thus the thing that you're actually selling them is pretty good too.

In summary, absolutely. The people who I interviewed were a massive factor in driving sales, and I'm incredibly grateful to them for that. But none of that would have meant anything if the underlying product hadn't had that time investment that anyone can make.

Jeremy: [00:54:51] The way that I found out about the book was through Hacker News. It was seeing the post and the title was very to the point. It's writing for software developers. I do writing being a software developer and I would like to get better at that. I click on the comments, I see your post, which, was very targeted, to hacker news. It understood people want to hear about the process or they would want to hear about Patrick, who is well known on Hacker News. You put a quote from him in your post. It was very effective at getting what I think the average reader would pique their interest and get them to click.

Philip: [00:55:31] Throughout the lifetime of that post on Hacker News. It generated almost 10,000 page views on my site. I'd imagine more because I think the average Hacker News user has more trackers and analytics blockers than the average web browser. But as a lower estimate 8,000 or so people looking at the page and converting at remarkably high rates.

To anyone who wants to launch something technical content related or anything that the audience might like investing some real time and effort in a great Hacker News launch is really worthwhile for sure.

Jeremy: [00:56:10] Another person that you interviewed for your book is Daniel Vassallo. Something that he's been really effective at is distilling thoughts into tweets. As you start to think about the next step of building your audience, how do you approach writing tweets versus more long form content?

Philip: [00:56:33] Yeah. This is something I've really been thinking about and struggling with over the past few days because I have this brand new audience and it's the biggest platform I've ever had. Over 750 people follow me on Twitter and that's a sign of trust that I take very, very seriously.

I want to focus on quality tweets over quantity and focus on creating threads to get around the 280 character limit. Because I mean, let's face it, I'm a long form sorta guy. I speak and write in a lot of words. And so what I focus on is taking something I've been thinking about or working on that day, distilling it into something actionable, and then providing that on Twitter and just hoping that people like it.

The other thing that I've been focusing on as I engage and grow this new audience is responsiveness. I'm trying to answer email really, really quickly. I'm not necessarily always doing a great job. Anytime someone responds to me on Twitter, I want to be answering them right back or at least liking the tweet or something.

I've sent so many direct messages. I actually had to look up Twitter's guidelines on how many you could send a day because I'm DMing people who follow me, who have interesting profiles and saying, Hey, you know, what do you want to read about on here? What do you want to know about the topics that I'm working with?

All of that is in the pursuit of figuring out what people want and then figuring out what I can provide and operating in the intersection of that.

Jeremy: It'll be interesting to see how you grow that audience and how you use Twitter in general.

Philip: [00:58:15] Yeah. The thing that I wake up thinking about every morning and go to bed thinking about every night is at this point, more than 20,000 people have looked at the writing for software developers landing page, which is super awesome, and ~560 of them have bought a copy of the book, which is also super awesome.

My question is, how do I get the rest of those people interested in this book? Or if it's not the right thing for them what is the right thing for them? What will get them contributing to this online community creating their own technical content for publishers, for themselves in their own learning, for the companies that they work for, the open source projects, and just expanding this idea because one thing that Angel Guarisma said in our interview right at the beginning that's been a real motivation for me over the past few months is there was a lack of a canon or accepted literature on technical content development. There's not a lot of books besides this one and a few others about the things that we do. There was that sense of responsibility as I was writing this book, living up to the title, writing for software developers.

I don't think I've made it there yet, but in my pursuit of this field, I have the opportunity to be definitive, and that's something that I take very seriously and want to do a good job of and take my time and do right. But in order to do that, I have to engage with the people who like what I've done so far and ask them what's next?

What can I make for you that will help you make the things you want to make? That's an incredibly privileged position to be in and I'm very grateful for it and I just want to live up to it.

Jeremy: [01:00:08] Earlier we were talking about when Chris told you that people skim through articles that surprised you. Is there anything else from the interviews that really surprised you?

Philip: [01:00:25] One thing I was surprised by is that many of the people who I interviewed were so strongly against advertising, which at the time I was a little confused by. I've never really minded ads all that much but I've also grown up steeped in them. Today with the sharp decrease in the number of advertisers on the market right now and thus the decrease in rates a lot of publications that have been relying on advertising are struggling to find sponsors and get the sort of revenue that they've been previously accustomed to. That was surprisingly prescient of my interview subjects. That's just what comes from all of those years of experience and seeing dips in advertising rates in the past. I've always thought of it as a very solid foundation to build a business on where in fact, it turns out it is not. That was one thing.

I wasn't necessarily surprised but it was really interesting to see the level of passion and commitment that everyone puts into the work that they do. That was very inspiring to me because sometimes it can feel like, okay, I've just got to churn out another article. Just got to get something that's going to get the editors approval and be decent and people won't hate.

And seeing the amount of effort that all of my interview subjects put into their own work, rekindled my passion for the field and really reminded me that every single article that I create has the opportunity to be my best work and that I should not waste that opportunity.

Jeremy: [01:02:06] One thing about your journey learning how to write and publish professional content. This all happened while you were in university. I don't think there's many people who think I'm going to write professional technical content. What was the path for you finding out that was an option and deciding that was something you wanted to do?

Philip: [01:02:29] So the great thing is that on the internet, no one knows you're a cat. That's a famous quote and I think that in technical content I have a picture and a byline and maybe a short bio, but that usually shows up at the bottom of the article, not the top.

And the great thing about publishing with some of the big names that I've gone with is their aura around my work gives the work the ability to stand for itself and people are able to judge the work rather than the author.

How I got into it was almost by accident. I started out doing some freelancing for a company based in Germany who was trying to localize their site for a United States audience. I rewrote their web copy in native English, to improve the perception of the site.

And then I noticed that they publish technical content. I asked if they wanted to pay me for some tutorials about how to use Django and they said absolutely. I wrote a couple of tutorials and it was a lot of fun. Then I thought, Hmm. If this one tiny company out in Germany publishes technical content maybe other companies do too, that could be cool. So I went around and I started looking. I found FloydHub, I found Smashing Magazine. I found all of these places.

This is a metaphor that I use in the book. Imagine if a college kid being me woke up one day and said, you know what? For my first attempt at journalism, I'm going to write the headline story in the New York Times. That would just go, nowhere.

But what's amazing about technical content is because there's so much demand for it even the biggest publishers are willing to give you the time of day if you write a good pitch. So after doing some research and writing some outlines I started pitching people and people said yes a lot more than they said no.

I've done a lot of other attempts at freelancing and entrepreneurship and such before this. Building products, all of that stuff. And reaching out to two people to have one say yes instead of reaching out to a hundred people to have one say yes is a massive change of pace.

This is what I'm going to wake up over the summer and do at 5:00 AM before work because just that cycle of feedback and validation was really, really inspiring and got me to commit to creating technical content as a important facet of my overall work.

Jeremy: [01:05:00] What's interesting is a lot of people when they see a page like Smashing Magazine or CSS tricks, not even just people in school, but people who work professionally. Most of them probably think to themselves there's no way I could write for this publication. You have shown that it's a lot more accessible than people think.

Philip: [01:05:22] Yeah. I think unfortunately a lot of people struggle with imposter syndrome working in technology and that's a huge issue in our field. It limits the people coming in. It limits the diversity of the field. It limits the things that we can accomplish together. But I do hope that seeing, Hey, this college guy was able to publish with insert big name here is helpful for people as they decide that they want to either do something similar in technical content or the equivalent in their own field.

Jeremy: Cool. I think that's a good place to start wrapping up, but is there anything that you felt we should have talked about or you wanted to mention?

Philip: No, I'm really happy with everything we talked about.

Jeremy: If people want to check out writing for software developers or see what you're up to where should they head?

Philip: [01:06:16] So my central hub on the internet is my website, which is philipkiely.com the book is available at philipkiely.com/wfsd. I maintain an email list that you can sign up for on that website. I'm also increasingly active on Twitter and occasionally post content to YouTube. I'm working on a video right now going through my first week's analytics on this book and looking at where the traffic came from and who converted. I think that's going to be a really interesting thing for people who are interested in their own product launch to look at. And I'd be really thrilled if you purchased a copy of the book or followed my other work.

Jeremy: Thanks for chatting Philip and congratulations on the launch of writing for software developers

Philip: Well, thanks, Jeremy. It's been a great time talking to you today.

Jeremy: That's it for my chat with Philip you can get the transcript for this episode at softwaresessions.com. See ya!