In this episode, we dive into the role of communication as a developer, how clarity is driving impact and how to self publish as an independent writer. Join us, as we chat with Stephanie Morillo author of The Developers Guide to Content Creation about how to write better as developer and how writing can take you from good developer to great.
Linode – Our cloud of choice and the home of Changelog.com. Deploy a fast, efficient, native SSD cloud server for only $5/month. Get 4 months free using the code
changelog2020. To learn more and get started head to linode.com/changelog.
Changelog++ – You love our content and you want to take it to the next level by showing your support. We’ll take you closer to the metal with no ads, extended episodes, outtakes, bonus content, a deep discount in our merch store (soon), and more to come. Let’s do this!
Fastly – Our bandwidth partner. Fastly powers fast, secure, and scalable digital experiences. Move beyond your content delivery network to their powerful edge cloud platform. Learn more at fastly.com.
Click here to listen along while you enjoy the transcript. 🎧
Hello everyone, and welcome to another brand new, wonderful episode of JS Party. Today we have some wonderful people on our panel. Suz…
And I’m also on the panel, I’m hosting. This is Divya speaking… And we have a wonderful guest with us, who you may heard of and you may be familiar with, because she’s written a lot, and is very into content creation, and talks a lot about developers, and so on… Stephanie Morillo!
Hi, hi! It’s so great to be here.
Cool. Stephanie, this is something we do with everyone, just to give a high-level introduction of who you are, what you do, any plugs that you wanna put as well…
Sure. So I’m Stephanie Morillo, I’m the author of The Developer’s Guide to Content Creation, which is a book that teaches developers how to generate new ideas, how to systematize their content and how to publish more confidently. And then I have a day job where I’m a product manager and I do a bunch of stuff and I run around and have a lot of meetings, which is awesome, which is fun… And if you’d like to know more about me and my books, you can go to developersguidetocontent.com.
Awesome. I think the stuff that you write about in your book and so on is really compelling, because something that’s really common in developer communities is that – and you hear this often, this assumption that “Oh, if you write code, you don’t have to be a good writer. It doesn’t matter”, and you’ve done a really good job, or at least you’ve advocated for the importance of just communicating and writing in a way that gets your points across, and at least explains the things that you wanna say… Which I think is really cool. Can you speak more to how exactly you’ve been talking through those ideas and trying to change perspectives?
[00:04:01.15] Yeah, it’s really interesting, because I have a Strategic Communications background, so for the first four years of my career before I moved into tech I was working in public relations for non-profits, and that’s a very writing-intensive job. And then about four years in I was involved in a project where one of our clients was migrating their entire website onto WordPress, and they had me do some really simple cleaning up of HTML tags on the frontend. I wasn’t doing any of the magical stuff, but I was really interested in that and I wanted to learn more, so a good friend of mine mentored me and taught me how to program. Once a week we’d meet for about 2-3 hours in a Starbucks, or at his place, and we’d just mess around with Ruby for a bit. Initially, I thought “Okay, I’ll become a developer. I really wanna become a developer. This is exactly where I wanna go.”
But over the course of time, I realized that it wasn’t the coding so much that I liked, it was actually messing things up and then writing about what it was that I did… And I wasn’t really sure how to marry the two. I knew, or I at least expected that writing and content was something that people liked, but it wasn’t something that was valued that much, and I knew that just because – you look at the salaries for a software developer, and maybe a technical writer or someone in a content position, and there’s a disparity. Now, they’re not the exact same types of roles; there are a lot of reasons and vectors that go into that… But people thought I was a little strange for wanting to stay on the content track, even though I wanted to continue in tech… But I knew that there was a need to teach people, and the best way to teach people is you have to know how to communicate, or at least you have to make the attempt to communicate your thoughts and your ideas with people. So I stayed the course…
You see, it was easy actually for me, even as a content strategist, to assume that “Oh yeah, a lot of people write, everybody blogs, everybody has a live stream, or something… This is stuff people know”, and I thought that it was self-evident, frankly, so I wasn’t even sure if I should write the book, because I was like “This is too basic. This is too foundational. People are gonna laugh at me. They’re not gonna want this.” And it wasn’t until I told people that I was doing it that people were like “Actually, no. This is exactly what we want. This is exactly what we need”, and I’m glad to have been in the position to have provided that.
It’s interesting you say that, because I enjoy the writing process as well, and I’m more on the developer side… And it’s interesting just seeing the comments that people make when it comes to writing. It’s sometimes really frustrating, because I think the assumption is like “Oh, if I wrote something…” The assumptions are on writing versus coding aside; in the event that someone does write something, they assume “Oh, I wrote it down, therefore it’s clear”, and oftentimes that’s not the case… [laughs] I’m like, “I don’t understand…” I’ve had to read a lot of people’s drafts before where it’s just a stream of consciousness…
And it helps if you know the person, because you’re like “I know exactly your thought process and the way you think and the way you speak, so I can distill information I need”, but there’s so many technical posts out there, and content and tutorials that are like that, that honestly, just because they exist – people assume just because they exist, it’s already a step up… But to me it’s almost worse, because it adds confusion, and I after reading a really long post, I have to go on and read extra things, just to gain clarity… And I think that’s a really interesting point - that people write, but are they writing in a way that actually communicates the point?
Yeah, that’s a sticky part, right? There’s a lot of stuff out there, but the quality varies. You have things that are really high-quality, and then you have things that can be reworked. I’ve had the opportunity to also edit a lot of technical content, and what I’ve realized is that a lot of folks haven’t had the opportunity really, or they don’t know how to find someone else to give them a look at what they’re doing.
[00:08:13.29] There is a part in the book where I talk about the importance of self-editing, and self-editing is beyond just using Grammarly, or just whatever native spell check comes with whatever software you’re writing. It’s really having another set of eyes review what you’ve created, looking at it from the reader’s perspective. To your point, you need someone who has that degree of separation from your content to help look at it critically and say “Well, from my point of view as the reader, these are the areas where I’m lost, that are vague, that I’m confused about, that may be too long…”
The thing about technical writing - and my technical writing specifically - I’m thinking about something like documentation… What is fascinating is that a lot of it seems to be really dry. There’s not a lot of room to be clever and fun, and that’s because when you go into official documentation, you’re going there with a purpose; you’re not going there to sit down and be entertained. You’re in the middle of something and you need to get it done quickly. But there is an art to distilling things down to their essence, and not lose anyone along the way. You have to spell really complicated things out in a way that allows people to follow what you’re doing, and you can’t lose them. And I think a lot of that comes to the fact that we don’t really have the equivalent of a writer’s workshop in tech.
MFA programs - people are used to sitting down and looking at other people’s work, and reviewing stuff… With us, we’re still at a point where people are just getting over their fear of creating, so they’re just like “Okay, well I’m not comfortable writing in a language that I’m not native in.” That is where we’re at. And I think slowly but steady we are getting to a point where people realize that writing is more than just putting thoughts to paper, publishing a blog post… That is a step of it, but it’s a process. There is the research at the beginning, there is of course the writing phase, and then you’re constantly refactoring before you get it out. And the idea of working with other people, having things peer-reviewed is something that I’d like to see more of, because it’s incredibly important… Not just because you need somebody else to spot out typos; that’s great. But you really want somebody to say “Actually, I was lost here” or “This didn’t do the behavior that I think you intended…” All of that important stuff, having somebody review for technical accuracy and other things is something we need more of, I think.
Yeah, I think it’s really great, because someone of your caliber is able to speak to both worlds, which I think is really unique.
It’s very meta.
It’s super-meta, yeah… Because a lot of times - and this is more just like every time I’ve had to… Self-editing aside; that’s very difficult as a process… And often when I write, I think I’m a good writer… [laughs] And I’m actually not. But the thing is, it’s interesting, because oftentimes whenever traditionally speaking - and I’m gonna make a broad strokes thing, and you can correct me if I’m wrong here, but oftentimes when it comes to technical blogs – documentation tends to be very specific, but blogs… You would write a very technical post, and often the person that reviews it doesn’t have the technical knowledge that you may have or your team has… There’s this disconnect that happens, and I think that’s sort of – I’ve seen in various companies I’ve worked a frustration there, because often it’s marketing that comes in and is like “We’re in charge of the blog, we wanna make it look nice, we wanna edit for grammar, readability” and so on. But the amount of process that goes through that, as you mentioned, which is like researching the idea, as well as writing a draft, and then editing that draft multiple times back and forth - I’ve seen so many engineers just get burned from that process, because they didn’t expect it…
[00:12:04.09] And also, I think there’s often because of the miscommunication this sense that both parties are like “You don’t know the thing that you’re supposed to be doing.” The engineers are like “You don’t understand the technical stuff”, and the marketing people are like “You don’t know how to write well”, and there’s this constant clash, to the point where I’ve been in companies where we essentially have to beg engineers to write blog posts… We’re like “Please, it’s really great for…” Like, I’m sure there’s SEO and all of those things that are involved, but it’s a really great exercise in just sharing knowledge within the company, as well as externally.
I don’t know if you’ve ever had to work with that kind of disconnect or that process that happens that makes people - or especially developers, which is your target audience - frustrated with the content creation process…
I have, because I was the editor in chief of two company blogs. I ran DigitalOcean’s company blog, and I did a short stint at GitHub also, running their company blog… And in both cases I was in the marketing department and I was sourcing, I was actively trolling Slack channels, and like “Oh, this engineer did this thing.” And then I would reach out to them and say “Yo, I think you need to write this blog post.” The process worked out well, and I’ll explain why…
There were a few things that I understood about what it meant working with engineers. For one, they don’t have all the time in the world to write their blog posts. They’re doing this in addition to their main job. So sometimes I would even reach out to engineering managers almost to advocate the value of having their engineers write for the blog, to get them excited and say “This is gonna be great for your team. This is gonna be great for your engineers. This will give people externally a window into what your particular team is doing.” Especially if it’s a team that’s working on platform stuff and things that are more internal-facing, that are not customer-facing, it’s awesome to give them an opportunity to talk to their work on the blog. So that was one important step for me - to reach out actively to engineering managers just to let them know what our thoughts were.
Secondly, I spelled out the process really – I was very transparent about what my process looked like, so I explained to them… I said “Listen, I know that you’re very busy, I know that priorities change within an instant… So what I wanna know is when is the earliest that you can get a draft? Should I reach out to you two weeks from now, or three weeks from now?” And if they said two weeks from now, then I’d put a reminder on their calendar, and I’d say “The only reason I’m putting this reminder on your calendar is just to reach out and ask if you have it ready. And if you have it ready, great. If you don’t, then I’ll come back to you at some later point.”
So in marketing, if you’re gonna do content management, you’re working on more than one blog post at one time. At any point I was having eight conversations simultaneously, just to get a blog post ready for two months from now… Because at any point, something could fall off. And then secondly, what I would recommend to the teams was if they weren’t comfortable as a writer, my recommendation was to record a stream of consciousness. “Record it and get it transcribed”, and I would tell them where to get it transcribed. Because then I told them “I can then take that and turn it into something with your feedback, and then we’ll shape it.” So that was one thing that I would tell people, especially for the folks that were really nervous about writing.
And then I always recommended that they had a technical reviewer on their team review the posts. Because we had blog posts on things like networking, and object storage, and a bunch of stuff, and no one person is gonna know all of that. You can be a fantastic technologist – there is this misconception, I think, from my experience, that to be a really good editor for an engineering blog post, you have to be deeply, deeply technical, whatever that means. But the truth is if you’re working in a company that has a bunch of engineering teams, with a bunch of different backgrounds, you’re not gonna know it all.
[00:15:57.14] We had people working with Go primarily, people working with Ruby, people working in all kinds of areas of cloud computing - no one person, no matter how fantastic or how deeply technical they were, were gonna know it all. So I told them very straight up, I am not the subject matter expert here, you are. But you need to get somebody on your team to review it from that technical perspective. So it would usually go through technical review with their team, and it made them comfortable, because these are people they talk to on a daily basis, they do code reviews with them… They’re used to certain kinds of communication. So at that point, then I would go in and I would edit and I would do heavy copy editing. It’s tricky, because you wanna preserve their voice. Sometimes I know some people get spurned by the editing process also, and I don’t know if this is what you were referring to, Divya…
…but some people get spurned because they sent something to whoever, and then they get back something that sounds like completely different than who they are. That’s tricky, because you wanna maintain that style, those standards, but you also want it to sound like this person wrote it.
So I had respect for the engineers, and I was never dependent on any one person that I was talking to to get things out on the blog. I was constantly hustling and looking for stuff, so it helped the engineers feel less pressured, because it wasn’t like everything was hinging on this one blog post… And because I understood that they were doing this in addition to their work. And I wanted them to like it; I wanted them to like the process, because I wanted them to write for us again.
It worked out really well. People were really excited, and the people who weren’t really comfortable writers, I tried my best to even frame how I would – like, whenever I made some edits, I made it really clear that you can reject a suggestion if you don’t like it. I can expand on something, I can let you know why I made a decision… Because it’s a vulnerable activity; you’re writing something and then you’re having somebody who is ostensibly really good at grammar looking at your stuff, and you’re gonna get really nervous if you just see a bunch of “Oh, no, no, no, no. She completely – what is that?!” So it’s a lot of “Oh, this will be okay.” Patting people on the back and walking them through it, because a lot of it is psychological too, you know? Emotional.
Yeah, it reminds me a lot of code reviews, because they always say things like “You shouldn’t be so emotionally attached to your code and have it be such a part of your identity that you’re not able to accept the feedback.” And I think when someone feels less confident about what they’re doing, such as “I’m really confident coding, and I’ve gotten used to getting constructive feedback in that area, but now I’m writing and I’m a little bit uncomfortable, and now I’m getting constructive criticism in that area, and I don’t actually know how to deal with that..” That’s where I’m sure that you do see that emotional sparring at times, and trying to figure out the right communication style for every person too is probably a challenge.
Oh yeah, absolutely. What I would do is I would usually have a 15-minute sync with someone if I reached out to them, and I’d say “Hey, I saw that you wrote about this on this Slack channel. I’d love to talk to you about writing a blog post”, and based on that, I’d get the sense of how comfortable they were with the idea, or if that was something they were even interested in… And then I would always adjust how my feedback worked according to the person. But I always wanted it to be a great – I wanted it to be a good experience. And I took that very seriously.
We all have areas where we need to improve, so even people that are really comfortable writing - maybe they haven’t had that experience working with an editor before… And I wanted people then to go back to their teams and say “This is something you should do. It was fun, it was low-stress. She wasn’t hitting me up at 5 PM for a deadline the next day at 9 AM… And if I needed to something back, I could.” And whatever the final product was, was something that they were gonna be proud of. That was my approach.
I think that’s so cool, that you advocate for writing content on the blog, and getting basically more publicity around the work that’s happening internally… But I like the approach, which is not just you taking on the brunt of the entire advocacy, but bringing people into the process and then having them go through the process, and then they become advocates within your team… So embedding them across. Did you ever come to a point where people would just come to you with posts, instead of you having to reach out?
[00:20:13.14] Yes. I even set up a submission process, so that if anyone wanted to pitch me, they could do that on their own. And we were getting pitches. It was a really good feeling when I left DO and blog posts that I had, that I sourced, were being published months out. That was the kind of backlog that I left. And people were like “Yeah, our team is working on this thing, and we’d love to publish it.” And I’ll say that I did it even with the leadership of the marketing at that time. I’m not really sure if that was the best approach… I really wanted people externally to read these posts and say “Wow, this is a company I wanna work for” or “They’re doing really awesome things, so I actually wanna try something on DO”, because we’re putting the engineer voice front and center.
That’s important with developers, because you don’t wanna hear from a marketer. We’re keeping it 100% here. You wanna hear from a peer, and your peer is not gonna sell you on something necessarily. They’re gonna tell you what it is. They’re gonna talk with a lot of enthusiasm about the things that they care about and that they like… So that’s why during my time there I really wanted it to be almost engineering-centric, because I wanted engineers to go there and say “Wow, these teams –” even the teams that are working on things that aren’t external-facing, or things that… You know, you might here billing and think “This is not that much fun”, but then the billing team tells you about this really awesome thing that the built, and now you’re like “Whoa… Okay, I didn’t realize that was something that I would be interested in.”
And people got excited, because I wasn’t asking for the best writers, I was asking for people who were excited about something and had a story to tell. And sometimes people were like “Wow, I didn’t even think this would be something that should be on the blog”, because I reached out; I’d see that somebody was doing one thing or another, and I was like “You know what, I want you to write about that, and I’ll help you. You don’t have to do it alone. You don’t have to be a great writer, or feel that you’re a great writer, or anything. I will make sure that this is something that you feel really good about.” So yeah, it worked. It was awesome. It was a great experience, I loved it. I worked with a lot of engineers and a lot of folks who, again, were all over the place in terms of their comfort levels with writing; I was really proud of every blog post that we put out.
That’s so awesome.
Suz, what have you been working on lately? Like, non-work related…
Oh yeah, that’s right. I’m liking your things. It’s so cool!
Thanks. Yeah, I really wanted to play with displacement maps this week, and then I got my migraine and I haven’t been able to look at screens. This is the first time I’ve looked at my monitor since Sunday.
So yeah, it’s just been really fun to learn. I learned 3D modeling when I was a teenager, when I was going through community college, and then I was like “I’m never gonna use this, but it’s fun.” And then I’ve just had this craving to go back to it recently, and it’s just been the most – I think because it felt really meditative to me, you can kind of lose yourself in it once you get on a good roll. There’s like a million little pieces you have to put together, so you’re just like “Well, I’m gonna do the coffee cup, and then I’ll do the table, and then I’ll do the chair”, and it kind of just like expands from there… So it’s just been a very relaxing activity.
That’s so cool. Nice. That’s so awesome. Yeah, it’s been beautiful, the stuff you’ve been creating…
Are you using Cinema 4D?
Yeah. I splurged on it. That was my pandemic splurge, it was Cinema 4D.
I’ve only ever used the one that comes through the Adobe products.
That’s Cinema 4D Lite. That comes with After Effects. So that’s what I did… I did the 3D for Designs course with that, and then I did my first Animal Crossing model of Leif’s plant cart, and then I was just…
Yeah, I’ve seen that. It’s so cool.
Thanks. I was running into the walls of where Cinema 4D Lite is really limited, so I was like “Well, I feel quite invested in this software. I really like it a lot more than Blender, so I will just buy a year subscription and see if I do anything with it.” It’s been pretty fun.
That’s so cool.
Yeah. What have you been up to?
I’ve been having the same inkling of doing something random. I’ve been playing around with this new game engine called Godot, which is sort of like Unity…
That’s so cool!
… but open source.
Yeah, and it’s sort of similar in the sense that I did a game development class in college, where we used Unity, and never touched it, because I was like “I’ll never use this ever again”, and lately I’ve just been like “I really kind of wanna go back and see that…”
[laughs] I love this nostalgia that we’re both having for like “Remember that one thing that was fun, that hasn’t been ruined by anything? I should go back to that…” [laughter]
Yeah. And I like that it’s also self-contained…
…because it’s so unrelated to what I do in my day job.
Exactly, exactly. That’s exactly why I’ve been into the 3D stuff. That’s awesome.
Are you making a game? I wanna play your game.
I’m between a dungeon crawler and a platformer… Because it’s sort of like different mechanics for both, and I’m just trying to work with understanding the game engine and understanding the connection between modeling things and then programming them. And that’s been the part – it’s a huge learning curve.
Yeah, that totally makes sense.
With Unity specifically?
I’ve been using Godot, which is sort of like Unity…
How do you spell that?
It’s like Waiting for Godot.
Yeah, that’s what I figured.
I don’t know what that phrase even means.
Oh, it’s a book called Waiting for Godot, by Samuel Beckett.
Oh, I feel very out of the loop. I see there’s a Wikipedia page about it.
I don’t blame you, it’s a very frustrating book to read.
[laughs] Well, the first result is the engine, and then the second result is the book, so thanks. I’m gonna look at that later.
Oh wow, look at that. Good SEO.
Yeah, I know. Seriously. Stephanie, what have you been working on outside of work? I know you’re doing your books stuff, but is there anything else that you’re–
Well, right now I’m on a break. I am on staycation, which is nice… So that’s what I’m working on - sleeping and watching Netflix, which is awesome… But honestly, it’s been one of those years where I’ve been furiously writing. It’s been a really long time since I’ve written quite this much… And it’s been great, because I’d wanted to go back to it.
I think I mentioned earlier that I’m a product manager in my day job, so I don’t get to do much writing outside of the business communications stuff. But yeah, it’s been mostly just making myself get into the habit of writing consistently again.
[00:27:59.26] Yeah, cool. Because I’d love to hear more about how you’ve been – because writing consistently is actually something that’s really difficult to do… I’ve tried to do that. I have done it only within like a month’s sprint, where I wrote every day, and it was really tiring. So I think it’s really cool that you’re doing – is there any specific topic that you’re focusing on, or is it like free-form type of writing?
It’s primarily blogs, and then short essays for a newsletter. My newsletter goes out twice a month now, and I’m blogging 1-2 times per month, so similarly, it’ll be like two weeks that I’m publishing something new.
In addition to that, I’ve kept a journal since I was 11, so that’s where all of my bad writing goes, just because – it’s nice to have a place where your writing can be really bad, you know?
You just do the thing and nobody’s gonna look at it, and nobody’s gonna judge, but it’s just a way of getting those creative juices flowing and getting into the habit more than anything.
Oh, for sure. I think often people assume that whatever you write has to be perfect. I’ve fallen into this category myself, where I’m like, “It’s just garbage and it has to be perfect!”
This is what I tell people, I’m like “Nobel-prize winners in literature, Pulitzer-prize-winning journalists - they all have editors and all of their first drafts are not fantastic.” Your first drafts are gonna improve over time, because you get into a rhythm, into a habit, but it makes me feel better to know that the folks that are the best and most prolific writers all have to work with editors, because their first draft is not it – you know, you have to constantly work toward that.
So if that helps at all, just tell yourself “You know, writer such-and-such (whoever you admire), their first draft…” We already know that when they got their manuscript back, with all of those red marks from the editor, they were just as frustrated as I’d probably be… And these are award-winners, so… They go through it, too.
Two of my most popular blog posts that I’ve written, I have banged out in a very short period of time, and just like thrown it out there because somebody’s been asking me to write about it; I haven’t thought anything of it, and then woke up the next day and it’s on Hacker News… So usually, I go through that shame of “No, that was not a real ‘proper’ blog post. I did not spend any time on it. I’m so disappointed about this…” [laughter] But it goes to show that sometimes if you hit the right topic, or even if it’s not perfect, if it’s helpful to people, people are still gonna have an emotional reaction to it and be very positive.
Yeah, I think it’s a good balance to have between – because I think there’s a sense of sort of like publishing your drafts, and I’ve heard people say that as well… But it’s an interesting balance to strike, because I think what Stephanie, you were saying, is just the consistency sort of makes you a better writer. The fact that you’re just consistently writing, and not making it super-finessed… So you’re sort of almost publishing drafts. I think that, in a sense, puts you in a really good place to write better as a whole. So if you were to sit down and actually write a post that’s for a bigger publication (let’s say), you’re likely to have something that’s a bit more polished than if you hadn’t gone through the process of just writing consistently.
Yeah, absolutely. Going back to what Suz said about the posts that you put together really quick are the ones that – I still can’t predict, frankly, which posts are gonna do the best. There are posts that I put out there that I’m like “Nobody’s gonna read this”, and then it’s the same thing - it gets picked up by a newsletter, and people say “This is exactly what I’ve been looking for”, and I’m like “Really? This is not even– why?!”
[00:31:53.15] People assume – like, yes, because a lot of my blog posts currently tend to have certain themes, I have a sense of what my audience is interested in… But if I’m putting out a blog post – I did a blog post on internal processes and documentation that I thought three people would read, and that was a blog post that everyone read. And then a post that I was like “Yes, everyone’s gonna run and read this about content strategy for developer relations”, and it was like five people. I mean, it was more than that, but you know, comparably… [laughter] You don’t know. It’s the ones that you put together in 15 minutes that people – I don’t know, they react strongly to.
I think too it also helps with the topics, in terms of how much finesse or polish a particular post needs. If somebody’s writing a technical tutorial that requires a significant amount of research, and that kind of thing, that’s gonna take them – they’re maybe learning how to use the particular technology as they’re writing the post… That’ll take some time. But if it’s something more like an opinion piece on a particular topic that they are very confident in, then that’s the kind of thing that might take less time to put out there.
So I guess what I’m saying is, in terms of how much time it sometimes takes to put things out, it really depends on the amount of familiarity you have with that particular topic prior to sitting down and getting it out. So if anyone is ever like “Man, I’m not like Suz. I can’t just put something together in 30 minutes and then it’ll be on Hacker News…” - well, I’m sure there is something you can do, but if you’re writing on like “How to use blah-blah-blah with the MERN stack?” and you don’t know the MERN stack that well, it’s gonna take you some time to learn that first, before you put your thing out. So yeah, it always varies.
One thing that I hear from a lot of people is based on that, where not only are they afraid that they don’t know enough about a topic, but they actually have trouble coming up with a topic in the first place… And I always feel very unhelpful in this case, because I usually say “Oh, I just got mad about something, so I wrote about it”, or “People kept asking me about the same things, so I wrote about it.” They tend to be my top two, where I just get so passionate about something that I want to, and it feels so defeating to say to someone “Just sit around and wait till you get mad about something”, because that’s no very practical advice. I’m interested in what you tell people who come to you and say “I don’t know what to write about, but I think that I do actually want to write, because I think I’d enjoy that experience.”
Yeah, that’s a great question. In the Developer’s Guide to Content Creation I have a little – it’s not even a formula, it’s more like a framework; there are four categories of ideas, so basically four ways of generating ideas for a blog post. The first thing is “Write about something that you know.” Write down a list of – just do a brain dump of everything that you know… And we’re not even talking about whether it’s 101 level, or 201, or etc. Just write down the things that you feel you have a good handle on. That’s one thing. Second, look at the things that you have done before, maybe in a different format. So if you gave a talk at a meetup, if you did something for work that maybe isn’t like 100% proprietary; maybe it’s something related to process, or how something was restructured, or something - that’s something you have, so you can always repurpose that and use that as the basis for new content. So that’s things you know, things you have… Things other people want to know.
Suz, you’ve mentioned that sometimes people will approach you with questions… But if you’re not at a point where people approach you with questions, people are asking questions all the time on Twitter, people are asking questions all the time on Stack Overflow, people are asking questions all the time on different platforms, and one of the examples I used in the book was when I was a technical writer on Ruby Gems we were trying to figure out how to write a guide for helping Ruby developers troubleshoot TLS issues, and there was no existing documentation about this anywhere. And when I did a quick Google Search just to see if people were talking about it, the question came up on Stack Overflow. So I was like “Okay, people are asking about it. It’s something that a lot of people wanna know about, so I’m gonna use that and turn that into a blog post.” That ends up happening.
[00:36:03.16] And then the fourth one - so things you have, things you know, things other people want to know, and then things you wanna learn. That’s the other category. What is it that you’re interested in learning? Writing a blog post is great – it at least gives you some kind of structure so that you can learn things. So if you’re like “Oh, I really wanna learn how to use Netlify”, and you’ve been making a point on creating a blog, and doing that with Netlify, then this gives you the opportunity to learn that… Because you’re learning it, and as you’re learning it, you’re writing about it.
So when you think about it in those four ways, things you already know - and there’s a lot of things we know about; it could be Git commands. You’re early-career developer and you’re like “I don’t really know that much about this stuff.” Actually, what about all the things that you learned up until now? All of that is good basis for things to write about. Things you already have - again, is it an open source project? Did you create something and put it on GitHub? Write about it. Write about the process. Write about all of the design decisions that you made. Why you made certain things that way. If you gave a talk before - hey, that is stuff that you can repurpose and make it into a cute little blog post. If you did a screencast - same thing. And then see all the questions people are asking in different forums.
And then lastly, what is it that you wanna learn? As technologists, we all wanna learn things all the time, so there’s never a shortage of possible things that you can write about when you look at it in those four categories.
That’s extremely good advice. Thank you, I’ll try and remember that. I think the learning-driven development is especially helpful, but it’s not always what you think about at first. But I know that a lot of people want to learn a topic, so sometimes they’ll even pitch a conference talk, and then they’ll learn how to do it while they’re writing the talk… I never really thought about applying that to a blog post. That’s really cool.
I got that idea when I was learning Ruby. My mentor suggested that I create a blog and use it as a way of documenting what I was learning. So every week I would write kind of like a recap of what it was that we discussed, and what I learned, and what was frustrating… And it was mostly for myself. There was no external audience. It was mostly for me. But it helped, because I wrote it as if there was an external audience, and I formatted it accordingly.
If you’re just learning something, you don’t have to have a blog. I think it’s important to say this, because I think a lot of people might compare themselves to folks who are really prolific content creators and such, who make a career of it, or at least use it to move ahead, and they’re like “Wow, this person has this amazing blog etc.” You don’t have to have a particular audience for your blog. Your blog can be 100% for you. If you want people to read it, that’s great, and of course, you’re gonna approach it differently… But it’s totally okay to create something that only you’re looking at and is for your eyes only, at least in the beginning, while you’re getting used to it. And then when you get to a point where you’re like “I want more people to see this and read this”, then you can widen your scope and change the kind of content that you write about.
But it was great, because I was already online anyway, and I was already using Ruby to learn how to create a Jekyll blog, and stuff; it was nice, it made sense. It kind of connected everything together.
Yeah. It’s so cool, because it serves as a really good personal documentation if you forget things…
Yeah… [laughs] I’ve used many of my own blog posts…
Yeah, 100%. You have a record of it.
Exactly, yeah. There have been times I’ve written about something and published it either to a company blog or something, and then googled and found my own blog post… [laughter]
Thank you, past me.
Every time I set up a new Windows laptop, I google my own blog post about how to make the terminal pretty. This was before WSL, and it was before the new Windows terminal, so it was so hard to get your stuff to look really pretty in the Windows terminal… So I always had to google that one blog post, or just go straight to my blog and pull out the XML files and everything that I linked out to. [laughter]
See? You just have to give yourself a pat on the shoulder for that foresight.
“Thank you for helping me out in the future.”
You’re the audience.
You’re writing for yourself. I sort of treat it that way whenever I write things as well, just to be like “This is for me, or for a future me, who’s likely gonna not know the thing that now-me knows.”
Exactly. One hundred percent.
We’re almost at the hour, and I wanted to just jump into the next section where we talk a little bit about self-publishing and the process that you went through there, because - you talked about this already, but you have a book that you published. It’s interesting to hear just the process of what that was like… So can you speak to that, what you went through there?
Yeah, I’d be happy to do that. I got the idea for the book – I would say it was last fall, and at that point I was like “I think there’s an audience for this book”, so I actually pitched it to a traditional publisher. It was a publisher that – really small, small press, but I really wanted to work with them for a while. So I filled out their book proposal template, and I sent it over, and they reached out and they were like “We really love the idea for this book, but we don’t know how to market it.” They were trying to figure out how to actually make it work with the existing catalog and how to pitch that in a certain way… And they encouraged me to reach out to other publications or to just self-publish it.
At that time, I started reading a book by an entrepreneur and developer named Amy Hoy. She wrote a book called “Just Effin Ship”, and it’s exactly what it sounds like; it’s very meta, because she wrote that book in 24 hours and put it out, and she talks about how to – and she uses the metaphor of preparing a Thanksgiving dinner, and how you have to get things done in advance. Like, okay, you know you’re gonna cook a dinner at Thanksgiving. What are all of the different steps that go into preparing for that dinner? So I actually started writing the book right around that time, as I was reading that… And then I decided that I would announce the book, even though I’d only written four thousand words. [laughter] I was like “I’m gonna tell people that I’m writing this book, just to see if people are interested.”
So it was a Friday and I wrote a tweet and I was just super, super-confident about it. “Announcement. I’m writing The Developer’s Guide to Content Creation. It’s gonna be great.” And then it was just like, like, like, like, like, and I was like “Okay, I guess I have to make this a thing”, so the next day I did the landing page, and I put the pre-order… Like, 4,000 words. 4,000 words. We’re talking very little here.
[00:44:06.24] So I was just like “Okay, I’ve gotta choose a date.” I chose a date six weeks out, and I did that because I wanted a deadline that I felt I could hit, but also put the pressure on so that I actually got the thing done. So I chose an arbitrary date in late January - this was around Christmas - and then the pre-orders started coming in, so I was like “Okay, I’ve gotta finish the book.” [laughter] So I wrote the book in 11 days. I wrote the entire first draft in 11 days…
I sent it to a reader, they did a full review over Christmas. I came back, incorporated their edits, I got some editors on Fiverr… I got two editors, because I wanted to make sure – I like having more than one editor, because sometimes one person will spot things that the other person may not, so it’s nice to have multiple perspectives there.
That’s a pro tip…
Yes, get more than one editor.
And Fiverr too, that’s interesting.
Yeah, there’s a perception with Fiverr that you’re gonna go with the cheapest editor, and I didn’t. I wanted to go with the editor that was gonna make the best book. And I had a budget for it. What I like about Fiverr is that a lot of the editors there, they have quick turnaround times. And because I was going with such a time crunch, I was like “I want something that I know that I can get back within a week, or a few days, or I’ll pay extra just to get it back even sooner.” So I kind of created the workback schedule once I knew when I was publishing it.
It was December 15th that I announced it, I was publishing it January 28th, so then I was like “If January 28th is when I’m publishing it, I have to know when I have to do the design, I have to do…” And I did all of that, by the way. The original cover was a Canva template that I found, and I did a landing page in Wix, the pre-order and everything on Gumroad, and the thing that I paid for was the editing, and then also for my reviewer… And then the book design and all of that - I did it myself. But it was basically early in the morning before work, so usually 7-7:30 to 9 AM. Then it’d be a full work day, and then from 6 to 10 PM I was working on it. And then I was working on it on weekends also.
Yeah, it was a lot of work. There are worksheets also, so it wasn’t just – so it was the book, it was the worksheets, and then of course, the formatting and the layout, the design, all of that stuff… And then the promotion. That was all me.
Yeah. Would you do it again?
I did it again. I published the second book in May. [laughter]
Oh yeah, that’s right. I forgot about that. So I guess that answer is yes.
Yeah, I did the Developer’s Guide to Book Publishing.
And that was incredibly meta as well.
Yeah, very meta. Because people were asking me about this self-publishing process… But I also wanted to give insight into what the traditional tech publishing process is, because unless you know somebody who’s had their book published by an O’Reilly or a Wiley, or an Apress - unless you know them, a lot of that particular process is completely opaque for people. I wanted to present it so that people who wanna write have the opportunity to understand both tracks, how they differ… Because neither one is better than the other, it’s just what you wanna do is different. It’s kind of like the “Choose your own adventure. If you wanna do the traditional publishing, you read these chapters. If you wanna do self-publishing, you do these chapters.” But yeah, I started that one about a month after I dropped the first one. [laughter] I would not recommend –
Just on a roll…
Yeah, I was on the – I was just like “This is intense.” And then Coronavirus happened, and that kind of messed up timelines, but I got it out less than four months after the first one.
That’s so cool. What do you think is the difference between – because you’ve done both now. You’ve written two books, and you’ve also written multiple technical documentation and blogs… What is the process like for both? I’m sure, obviously, one is more intense, but can you speak more to the ideation, and then moving into the actual writing process?
[00:48:01.08] Yeah, writing blogs is, for me, a much more lightweight process. I might take some time mulling over an idea, and maybe jot down a few things in my Apple Notes app, but then I’ll sit down and I’ll hammer out a blog post in half an hour, sometimes less… It could be anywhere between a thousand to 1,500 words. So I can write very quickly, but because the blog post is pretty much just writing some research, there will be some research involved, and then some light editing… I can write a blog post and have it published within a day. Versus a book - it’s really easy to have scope creep with a book.
The same thing is true of a blog post also, depending on the kind of topic at hand. I always keep my audience in mind, I always try to define what the goal of it is, so that I don’t go off on a bunch of tangents… But with a book, you’re doing that at scale, because it’s easy to just fit everything in, or “What if this? What if that?” It’s like over-packing for a trip, like “How do I get this down to a weekender bag?” And that’s exactly what makes the process harder, because you have to write a full-out outline, and then as you write, you realize that you have to continuously refine that outline… And then you may find that “Oh, maybe I wanna add this”, but actually, does it detract or does it add? So you have to be, I feel - with even longer blog posts, but certainly with books, you have to be very ruthless in cutting down. You have to kill a lot of your darlings in order to just give people “This is it, and this is what you’re getting”, so that you don’t overwhelm people, or just lose people.
But with some blog posts you can say that, too. Like with tutorials. A tutorial blog post, “How to do blah-blah-blah”, it’s really easy to give everything with the kitchen sink. But you almost have to think about it as like – the way I like to think about those kinds of blog posts is like… You know the recipes you get with a Blue Apron or a Sun Basket subscription? They fit on a card, right? And they’re not superfluous and they’re not using all these great words. Every word there is there for a reason, and they’re not gonna give you the back-story and all that fun stuff. They are “You’ve gotta do this, you’ve gotta do this, you’ve gotta do this.” But the great thing is that as a result, you pretty much don’t mess up the recipe. It doesn’t matter the level of cook you are, you’re pretty much gonna get the desired outcome. So you know, that’s what I would say – Suz was like “Yay…!”
Yeah, it makes me wonder what would–
But it’s true, isn’t it?
Yeah, but what would a tech tutorial blog post look like if it was written the same as recipe blogs? It’s like, “I remember when I was a child, punching away at my Tandy computer… And I was thinking, I would just love to have the ability–” You know what I’m saying? I’m just wondering what that would look like.
[00:50:55.11] I mean, it’s funny, because sometimes you’ll see blog posts that have that intro where – and I do that, too; you have a little bit of context/background… But even within the recipe, you might find that there’s bloat. There’s certain phrases that – or even the steps are kind of messed up. Step three was actually supposed to be step two, and stuff like that… The reordering… There’s that. So even without the whole back-story about this in Cabo, and my grandmother, and all that - even without that in the technical blog post, we’re still probably not as straightforward as we need to be. And it’s not that you need have to do without any kind of color, or that you have to sound super-dry and boring, but it’s really easy to miss a step or miss a word, and then people get stuck.
So I think going back - and I know this was very long-winded, so I may have lost my train of thought for a bit… But I think with both certain kinds of technical blog posts, like a tutorial where you’re teaching somebody how to do something from start to finish, and a book, you have to outline, you have to be very ruthless in cutting things out, and you have to make sure that every step that is there and every word that is there actually means something. And don’t just go by your own judgment. Have somebody else review it, so that they can validate or not your hypothesis that this particular thing actually is doing what it’s supposed to be doing.
Yeah, I think it’s so important that you mention that, and it’s so pertinent as well… Because people think the writing process is creative, and so it just flows, but I actually think what you’re speaking to is that it’s much more rigid – well, not rigid, but there’s some structure to it, which is you outline what you want to say, and then you write the thing, rather than let your ideas flow… That’s a different kind of writing. But I like that structure as a way of making sure that you actually can write the thing within a reasonable amount of time, and also you don’t get burned by the process.
Yeah, a hundred percent.
Awesome. So I think we’re at time. I wanted to thank you so much for coming on, and before we close, I wanted to – Suz, did you have something to say?
No. Did I make a face? I always make faces and I don’t mean to, I’m sorry. [laughter] I do that all the time.
It’s fine. It’s totally fine.
It’s just my face.
[laughs] Before we close, I just wanted to also give you an opportunity to make a plug, and where can people find you, and that kind of information.
Sure. On Twitter I am @radiomorillo. You can find me at StephanieMorillo.co. I blog once or two times a month. There’s links to my newsletter if you’re interested… And of course, if you’re interested in purchasing the Developer’s Guide to Content Creation, you can also find it there. I frequently tweet with tips about writing and content in general, so if you’re interested in seeing what kinds of gems I drop, there’s a bunch of stuff on Twitter.
And then, of course, I have opportunities for developers who wanna work with me one-on-one. So if you would like a one-on-one session, you can find more information about that on my website also.
I definitely second that you have nuggets of wisdom on your Twitter.
I’m always clicking through to your threads every time.
I appreciate you.
Our transcripts are open source on GitHub. Improvements are welcome. 💚