Transcript for Episode 209. Getting Started with Technical Writing with Stephanie Morillo
[00:00:00] MN: Hello. Welcome to the Rabbit Hole, the definitive developers’ podcast. Live in large in New York. I’m you host, Michael Nuñez. Our co-host today.
[00:00:07] DA: Dave Anderson.
[00:00:08] MN: Today, we’ll be talking about creating developer content.
[00:00:12] DA: Everybody's making content these days, you got to get the live stream podcast of my blog.
[00:00:20] MN: Exactly. I'm going to go on Twitter and I'm going to throw nothing but hashtags all over the place, to make sure that you get access to my content right now.
[00:00:31] DA: I'm really not good at writing, though, or finishing blog posts. I’m very good at starting blog posts, but thankfully, we have someone here who is good at finishing blog posts.
[00:00:38] MN: Today, we have an esteemed guest, Stephanie Morillo. How's it going, Stephanie?
[00:00:42] SM: I'm doing well. How are you doing?
[00:00:43] MN: Doing all right. Tell us a little bit about yourself.
[00:00:46] SM: I am by day, I'm a Technical Program Manager at Microsoft. I run the AV Testing Program for azure.com. By night and by trade, I am a content strategist. My area of specialization at the moment is Developer Content Strategy. I've done everything from marketing, copywriting, to product copywriting to developer relations.
[00:01:09] MN: Okay, so I guess I'll start out. Am I doing it right? Am I just going on Twitter and just typing all the tech Twitter keywords, to make sure that my content gets as far as possible. Is that the way to go?
[00:01:21] DA: #content, #tech. Yes.
[00:01:24] SM: Don’t use any hashtags. Don’t use any hashtags. Leave the hashtags back in 2011 where they belong. That's where we're going to leave the Twitter hashtags. What you got to do is you have to tweet frequently, and you have to engage with the right people. By engaging, I don't mean just liking and retweeting. You have to have conversations, like your two cents. Start actually developing relationships with people has to be social on social media. That's what you got to do.
[00:01:52] DA: That sounds very, very much intense. I’m just getting anxious, just thinking about talking with anyone.
[00:02:00] SM: Talk to people on social media?
[00:02:02] MN: Doing the social part of social media, that's the difficult part. Yeah. I mean, as Dave mentioned before, there's many different ways to get content out there, right? From live streaming. We had Melissa, a couple weeks ago to talk about how she programs with the world via YouTube or Twitch. I imagine, our podcast is a way of doing it. Dave, you're actually creating content right now. Do you realize that? It freaks me out when I say a lot.
[00:02:25] DA: I could just pretend that I'm in my room by myself. Even you guys are not there. No, I'm kidding. I'm kidding.
[00:02:40] MN: When I think of creating content, a lot of the times, I do believe that it's like writing a blog. You have written a blog post about an introduction to technical writing. Could you walk us through the beginnings of starting a blog, the traditional blog way, which is through punching keys and getting my content out there.
[00:03:04] SM: Going back to what you said earlier about creating content, for the most part, you think about it as blogging. I think about content as much more holistically than writing content. Of course, like you all mentioned, podcasting is one form of content, live streaming is, videos, tweets, depending on the information that's being relayed can be content, but so can open source projects, or demo, things like that. Content is really holistic. Just think about any kind of vehicle that you're using in order to kind of relate information, whether that's educational, entertainment, or informational, that's content.
When I think about blogging, in particular and the way developers write blogs, there are multiple different types of blog posts that a developer can write. A developer can write a step by step tutorial. Think about it like a recipe, like a recipe from I don't know, Blue Apron, step one, you do this. You have your list of ingredients, which are your prerequisites. Before that you say, “Okay, this is what we're going to make, this is the dish.”
Then you go into the ingredients, which are the prereqs and then you do step by step, this is how we're going to build the thing. Then you break it down step by step. At the very end, you say, “Okay, great. Now you have this dish, which is whatever and it's working and this is what you can do next.” That's probably the most popular type of blog posts.
[00:04:17] DA: Like a tutorial focus, almost. Something like, yeah, just follow on.
[00:04:29] DA: Last one is so weird. You won't believe it.
[00:04:34] MN: Broccoli.JS.
[00:04:36] DA: Broccoli.JS. Whatever that is.
[00:04:37] SM: No we’re not doing this. We’re going to leave broccoli alone. We’re leaving broccoli alone. We’re leaving it out in this conversation.
[00:04:43] MN: Good. Yeah, you said so listicle is a way of framing the content as well.
[00:04:48] SM: Yeah. I think a lot of people tend to overthink blog posts. I think, listen, going back to how we learned how to write essays in school, in the beginning, you have an introduction and in your introduction, you state your thesis, which is, this is what this blog post is about.
When you give people all the information, the context they need in order to follow the rest of the blog post, which is the body and the body is all of the sections that go into more detail. Then at the very end, you conclude and the conclusion is a summary of everything that you just said and then you might even want to include resources for additional reading, continued reading, continued learning, so that people when they finish your blog post, they can then take the next step, which you have identified.
Really, when you think about it, just think about middle school essay writing. Remember, you have your intro, you have your body, which is the meat of what you're creating, and then the conclusion, which is essentially a summary. Doing something like that, you can't go wrong.
[00:05:46] DA: I just threw out all of my middle school notebooks, a few weeks ago.
[00:05:49] SM: Unfortunately.
[00:05:51] DA: My parents were like, “Please. Just throw the –”
[00:05:55] SM: They saved it?
[00:05:56] DA: Or they don’t want to destroy them.
[00:05:57] SM: It was so nice.
[00:05:58] DA: In their basement. They’re like, “Please. It's been 20 years.” We can't do this anymore.
[00:06:04] SM: We can’t do this anymore.
[00:06:06] MN: My mom definitely has a ton of my middle school books, and my handwriting is so horrible, nobody could read it. I'm sure, she's there to keep the house warm. That’s all it is. Just to keep the house warm.
[00:06:16] DA: Yeah. Insulation. Yeah.
[00:06:17] MN: If they need it, they're probably going to use it to burn it to make more heat in the house maybe. I don't know. I think one of the things that I use blogs for – I have a blog, and it's from four years ago. Please don't judge me. One of the things that I've returned to in one of my blogs is, when I forget how to do something, I know that I have a blog written on it, because I know I'm going to forget.
[00:07:05] SM: That's what a lot of people use the blogs for though.
[00:07:07] DA: I like that. It lowers the pressure too. Because it's like, it’s not like “Dear World, here's the idea that's going to change everything. It's now just Dear Mike, six months from now, you dummy. You forgot how to destructure an object. This is it.”
[00:07:37] SM: It depends on what your goal is, if your goal, there are people that start off their blogs, solely with the intention of documenting exactly what you described like certain problems that they came across, or to try to write down so they can remember things for the future. So the target audience of their blog is generally themselves. If other people benefit from it, that's great but anytime they come across something, they kind of populate it on there.
[00:08:01] DA: Yeah, I do feel the blog posts that have resonate with me and change the direction of my life, have been blogs that I've done that, we’re, they're like this is my journey and I'm like, “Oh, this is so relatable and this could be me. Why don't I try that?” Then it really works very well. If you keep it up.
[00:08:22] SM: That's because I think a lot of people don't get really self-conscious in that way, right? They’re presenting it like, “Okay, this is the problem that I'm facing.” I’m supposed to, “I'm the expert on this topic and this is what you're going to learn.” I think when people write - I think when people have to put their teacher voice on, it gets a little bit nerve wracking, because at that point you're, “Oh, wait, I actually have to know what I'm talking about.”
[00:08:42] DA: Right. You got to be right.
[00:08:44] SM: It's a mental hack. It's a mental hack. You just say, “Okay, this is something that I recently learned, and I'm just writing it so that it can help somebody else.” This is how - it's less pressure when you're –
[00:08:55] DA: It is a fact. No one could dispute that you recently learned it. Yeah, I always feel I run into this problem, where I cannot define when a blog post is done. I want to write something that is making a statement, or clearly telling something, and I just keep on going over and over and over it. Never actually getting to done.
[00:09:26] SM: Is it, in your case, do you find that you get a lot of scope creep? Is it just that you start adding too much to it? Or is it just that you're overthinking what you have in front of you?
[00:09:35] DA: I think I have a vague thesis and my thesis isn’t concrete and then I just keep – I think it is scope creep, because it's just “Okay, keep writing, keep writing.” It’s like, “Okay. Now, I am trying to prove a book. I'm not qualified to do this. I need to do my research in order, so I can complete my book.”
[00:09:56] SM: I found that it helps to step away from a piece of writing that I'm kind of stuck on. I'll step away from it for a few days, and I'll come back to it, not as a writer but imagining myself as the editor. Imagine you had the teacher with a red pen that was going over your work and was like, “Yup, nope, nope, no.” The reason I recommend waiting a few days is because there's a bit of distance between you and the work that you've created.
You have to look at it as if you were the editor that you were hiring to kind of, you look at it from the perspective of the reader. Take yourself out of it and get out of your own head. Don't worry about, “Oh, this is what people are going to think or whatever.” You just have to think, “Okay, I need this to be clear. Is it clear? No. Okay, what can I change? What can I take out? Am I being redundant?” We tend to be really redundant, without even thinking because it's stream of consciousness when we're writing.
Then if you find that it's still an issue with the thesis being vague, then definitely take some time away try to figure out what the scope is, because before you write a blog post, you should know, more or less exactly what you want the reader to take away from it at the very end. That should be very clear, because that's essentially what you're going to be starting off with. You have to say, “This is this blog post and the goal of this blog post is to enable you to do blah. If you can't get to that yet, then that means that you still need some time to figure out the topic, or figure out exactly where you want to focus in on.
[00:11:50] MN: That makes sense. It sounds largely, the thrust of it, is like do less, chill out.
[00:11:56] SM: It's hard. It's not easy. I'm not saying it's easy. It's not easy with technical content, there's a lot of information, you have to recall a ton of information and present it in a way that is concise and that people can read and understand. That's not easy. When we're first writing, we're so concerned with getting all of our thoughts out, that you have to go through multiple stages of drafting, to get it to the point where it's something that you feel okay with sharing with the world.
Let's say you get to that point, you've edited and you reviewed, and maybe you had a friend, review it, and you're still like, “Okay, should I publish this?” Yes, publish it, don't think about it twice, because otherwise, you’re not going to snap out of it.
[00:12:38] MN: You’re never going to publish it. Yeah. You're never going to publish it.
[00:12:40] DA: I thought you’d end up having a pair too, where it's like, social support, you can kind of validate and push yourself to be done.
[00:13:19] SM: I prefer the platform that will enable you to press publish the soonest. I find that a lot of people get really hung up on figuring out what their stack is going to be, that they don't actually – people get so concerned about building the perfect blog that they don't think about the stuff that the blog is supposed to – that’s supposed to live on the blog.
If you are like, “Okay. I don't know exactly what I want to blog right now. I don't know what I want to blog on, but I know that I have ideas, and I don't want to spend all of this time.” Start with the one that is the easiest for you to get off the ground, then you get in the habit of writing. While you're doing the writing, then you can take some time to investigate, “Okay, where do I want my blog to eventually live?” Then you can migrate all of that content onto your blog, cross post it, and then eventually make your blog, your personal blog that will let you build out the main one. Whichever one is going to enable you to start publishing right away, that's the one you go with.
[00:14:12] MN: Do you have any top three? I mean, if then – I’m sponsoring the podcast, unfortunately, not giving us money. If you had to tell someone, “Hey, start writing it at this place.” What would that place be?
[00:14:22] SM: I think GoCMS is a really good one. It's a lightweight CMS. It’s open source. I believe it allows for self-hosting. You can edit in markdown, so it's great and they have a bunch of templates. You don't have to do anything out of the ordinary to get a blog up and going. WordPress, you can’t go wrong with wordpress.com, especially if you decide to map a domain to it, just because they've been around forever and it’s the same deal. They have a bunch of templates, they make it easy for you to put something on there and publish.
If you want to do something that's more, I would say, if you want to have your blog, on a forum or a place where other developers tend to go to other places to look out would be dev.to and Hashnote. Both of those are blogging platforms, specifically created for developers. They have hashtags. They all enable comments, and they're very, very easy to get off the ground. You create an account and you're ready to start blogging.
[00:15:16] DA: For WordPress, where's my street cred? I got to have the Gatsby headless CMS.
[00:15:25] MN: Middleman, you got to use a middleman, that's on my oldest blog. I see as a middleman Jekyll.
[00:15:30] SM: A lot of people are still using Jekyll, by the way. A lot of people are using Jekyll, a lot of people are still using Hugo. Hugo I know is newer than Jekyll. I was actually really surprised to hear it, because I actually tweeted this a few weeks ago. I got 500 responses, I didn't know if some people talked about my blog. Actually I know better – I knew that -
[00:15:46] DA: Because people are more passionate about the stack than the content.
[00:15:49] SM: I needed that real quick. I was like, “What are you using to book your blog?” Everybody's was like, “11D, this, that, the third, Nuts.JS.” I was like, “Okay, I’ve got to mute this.” Believe it or not, a lot of people are using Jekyll.
[00:16:04] DA: Okay, so if I have a question of should I write a blog post or change my static site generator from Jekyll?
[00:16:10] SM: You are going to write blog posts? Absolutely not. You're going to do the blog post first.
[00:16:12] DA: Oh, come on, but I don’t know how to use Gatsby. Oh, man.
[00:16:15] SM: You know what ends up happening? People build the blog. First, they take months to build a blog, and then their first blog post is, how they built the blog, and then they don't blog again. That's what happens.
[00:16:25] DA: Have you seen my blog?
[00:16:27] SM: Did I just describe your blog?
[00:16:31] DA: Get out of my head.
[00:16:33] MN: Dave feels personally attacked right now.
[00:16:37] DA: Okay, so there's another thing. I did write that blog post. I was very proud of my template. I was Oh, that's such a cool looking template. It looks so neat and then I ran lighthouse against it and I was like, “Oh, my God, this is a trash fire.” I’m like, “Should I write a blog post? Or should I optimize my SEO on page performance?”
[00:17:29] DA: I got those big images, real big.
[00:17:33] SM: No, sir. I think there's a site called compressor.io, where you can like – the quality stays the same and you just put it on there and then it'll – then you just re-upload it to your site. You want to make sure you have your all text. It’s a lot of stuff. Do the blog post first and then get to SEO, because the SEO I think is important for -
[00:17:51] DA: The accessibility too, I know a lot more about accessibility that I did as well and I'm pretty sure that no person is able to access my website unless, I mean, well, yeah. No matter their ability, maybe.
[00:18:05] MN: If they use a screen reader, it's like, they're lost. It's just going to shout at them.
[00:18:09] SM: You know what happens to a lot of us. I think for those of us who don't use assistive technology, it's really easy to just completely forget to put all texts in, forget to put descriptions in even with SEO is easy to forget, “Okay, do I have to put in a Meta description? How many characters?” All of this stuff, we forget about it, because it's not something that we think about in our day to day.
If that's just something you add to your little checklist before you publish a blog, if you're going just say, “Okay did I edit everything? Did I add my all text?” Then that's the way you can start making it into a habit.
[00:18:41] DA: Yeah, I'm almost feeling inspired to start writing blog posts about optimizing my blog.
[00:18:47] SM: It’s actually not a bad idea though. It’s not a bad idea. I approve of this message.
[00:18:54] DA: There you go. Okay. There you go.
[00:18:57] MN: What if it is, I guess, so optimized that you can't optimize it anymore. You're going to continue blogging?
[00:19:01] SM: You're going back to blogging. Yes.
[00:19:02] DA: I only said, I will ascend up into the SEO clouds.
[00:19:07] MN: There you go. Awesome.
[00:19:08] SM: Oh, goodness.
[00:19:10] MN: I do have a question. As I mentioned before, I have a blog that's five-years-old. It's sad. I really tried to use, what is that? I think I use middleman with rails, and it's marked down. I don't know why I do this myself, because I'm a horrible designer. I can't pick colors or styles or templates for beans. It's ugly. It's blue or gray and it just doesn't work. What do I do with that content from five years ago that I mentioned myself, I refer to from time to time, but it's just sitting in a very old-looking site?
[00:19:42] SM: First of all, it sounds like you do eventually want to migrate to a new - Yes. Okay.
[00:19:47] MN: I do want to say that I'm inspired now. We chopped it up a little bit and I want to start writing content and I'm not going to write for that old site, but do I bring those over with me and then start again? What are your thoughts on that?
[00:19:59] SM: You can bring your old content with you. You don't have to bring everything. You can go back and decide, “Okay, is there some content that I want to keep, some content that I don't?” I feel it's nice to have a blog and use it - so here's the thing is that blogs are actually dynamic. I know that there are people that keep their archives from 2008, unless you're a food blogger or somebody who – Basically, unless a lot of the content is evergreen, you don't necessarily need to have all of that content there.
You might go back and say, “I wrote this blog post in 2016. I refer to it from time to time.” It is old, but what you can do is you can update it, and then publish it on your blog again, and then anything else that you think is completely irrelevant, anything that you don't like, anything that doesn't resonate with you anymore, you can just completely remove. I mean, I would say that just make sure you have a repo or something, so you can access it so that you can kind of, you keep a record of your writing. You can bring it over. You have the choice of selecting what you want to bring over when you migrate.
[00:20:55] MN: So like, evergreen content, or stuff that is not as green, you can update it to the new blog post. Stuff like, if I got a blog post on handlebars.JS, I think I should leave it at the past.
[00:21:10] SM: You should leave, you know, yeah.
[00:21:11] DA: Yeah, just delete it, Mike.
[00:21:35] DA: Okay, I feel liberated. I'm going to delete my blog now.
[00:21:38] MN: All of it?
[00:21:42] SM: No, no, no, no, no, because then you're going to go - the problem is that there's going to be this problem, you're going to go back to deleting the whole blog and then you're going to spend a lot of time trying to figure out exactly what static site generator. Then you’re going back to having the first blog post of this blog be, or how you build a blog. Then, no, no.
[00:22:01] MN: But that he's going to talk about how to optimize for accessibility.
[00:22:05] DA: Right. The new one.
[00:22:03] MN: Then he’s going to talk about more accessibility topics.
[00:22:08] SM: Then what happens when this blog goes stale? Are you going to update it? You have to keep content on there. You got to put content. You got to keep it fresh.
[00:22:15] DA: Yeah, I think that's a great point. It's about consistency of the habit. I think that's the only reason why we still exist as a podcast is because we have been consistent. Every Wednesday we show up. Then if we show up every Wednesday, then eventually, you put out 200 episodes.
[00:22:33] MN: Yeah, exactly. It's just usually like, “Hey, Dave. What are we talking about? Then we chop it up, make it happen, content’s made. That's what we've been doing and consistency has been key for us. I imagine it will be key for you. If you're starting your blog.
[00:22:48] SM: That's correct. Yep. You already have a system in place for being consistent. The two of you, you've created it, so that it works with your schedule. You all are able to show up and you're able to make it work. The same thing applies with assuming you want to blog, assuming that something you actually really want to do then, bring that over a blog. I say that because I don't think every developer should have a blog. Every developer does not need a blog. I think every developer that wants to create content, needs to figure out what content vehicle is the right one for them.
Well, it seems podcasting is one of your favorites. That's a content type that you really like. So maybe if that's something that you can be consistent with, you can continue with that. If that YouTube video, short YouTube videos are your thing, then that's what you do. You don't have to blog, if that's not your thing.
[00:23:35] DA: Right. I mean, that's true. I think that's kind of the really egalitarian thing about it, is there are so many ways to express yourself that you can find a way that makes you happy and you can keep consistent with.
[00:23:50] SM: Yes, correct.
[00:23:52] MN: Stephanie, how can people reach out to you?
[00:23:55] SM: You can find me on Twitter @radiomorillo or you can find me on my website at stephaniemorillo.co.
[00:24:01] MN: Awesome. You have a book on creating content?
[00:24:05] SM: Yes, I do. I have an eBook called The Developer's Guide to Content Creation, which includes 14 guided exercises, there are templates, and from start to finish to show you how to get started with content creation. You can find that at the developersguidetocontent.com.
[00:24:20] MN: Awesome. Right. I'll start by writing and I promise that I'm not going to look for the stack I want to write it in. I'm going to say that. I was going to try my best to do this writing and I hope that everyone out there gets to see some cool content has been created. Love to see that content. Feel free to tag us @RadioFreeRabbit. Or you can hit my personal Twitter, Google Mike.
Follow us on Twitter @RadioFreeRabbit, so we can keep the conversation going. Like what you hear? Give us a five-star review and help developers just like you find their way into the Rabbit Hole. Never miss an episode. Subscribe now however you listen to your favorite podcast.
On behalf of our producer extraordinaire, William Jeffries, and my amazing co-host Dave Anderson, and me, your host Michael Nunez, thanks for listening to The Rabbit Hole.
Links and Resources:
Our seasoned cross-functional agilists work with you to develop technology, ship product and deliver value. We leverage our diverse expertise across industries and throughout the organizational growth cycle to your benefit. We bring best practices, emergent practices and creative solutions to your problems.