Hello! My name’s Amanda, and I’ve edited hundreds of tech blog posts.
As you can imagine, I have a pretty good idea of what, on average, bloggers grapple with. Today, I want to talk about the very first thing you should master: the basic elements that make your post intuitive to follow. More specifically, we’re going to talk about how to give your reader great “this post is about” statements, bullet-like subheads, and satisfying conclusions.
But before we get started, let’s lay down some basics.
First, a Note on Why You Need to Follow Patterns
You can have amazing word choices and beautifully crafted sentences—even advice that would change people’s lives, if they just had ears to hear. You could have all the elements of a truly remarkable blog post. But if it doesn’t flow in a way that feels natural to readers, they won’t appreciate all the things that are good about your post.
Okay, but let’s not talk about readers for a second. Let’s talk about you. No one likes being put into a box, you included. Me included! I remember hating writing five paragraph essays in school. Stupid theses! Stupid formulaic conclusions! Ugh, what a damper on my creativity.
But here’s the thing about communication. To reach one another, we DO rely on patterns. Think of the superhero movies that follow good vs. evil patterns. Think of underdog stories where we root for the one no one expected to win out. And think of all the stories from mythology that stick with us—the hero’s journey and such. (Harry Potter is a modern take on the hero’s journey, so there’s the evidence that the framework still holds power.) We connect with these patterns. We expect these patterns. And 99% of the time, not getting what we expect makes us confused and distracted…and, if you talk to Dexter fans, angry. You have to master delivering the expected before you can get creative.
You see where I’m going here. Readers are expecting certain things, and you need to master structure before you can attempt form play.
All right, so let’s chat about the three things I laid out above. First, lay out what your post is going to be about in a sentence or two. Do this before you begin to draft—it will help focus your thinking, and it will set the stage for the rest of the post.
If it helps, just fill in this template:
“This post is about ________.” You could also use “This post will cover __________.”
If you want to really solidify things in your mind and to your reader, you can also add this:
“As a result of learning this, [your life will be better in ________ way]”
(Bonus: thinking about this statement will help you write your conclusion, too.)
Is this formulaic? Sure. But there’s a reason it works. Step into your reader’s shoes.
When you’re reading something that just leaps straight into information, you’re forced to “hold” that info in your head. You’re waiting for the author to get to the point and tell you what to do with the information. And while you’re distracted doing that, you can’t focus on connecting with author’s point, mapping it to your own experiences. After all, you’re more focused on just trying to understand the goals of the post. (“Why is she telling me this?” “Where is she going?”) Eventually, if you have too much info to hold, you just drop it and give up.
But what if the author laid out the point of the post right off the bat, in the intro? It would have prevented this distraction.
One last tip. Put this statement near the end of your intro for maximum lack of reader surprise.
Examples
Let’s look at a few examples. Here’s the one from this post:
Today, I want to talk about the very first thing you should master, which are the basic elements that make your post intuitive to follow.
Here’s some from some HS posts this week:
In this post, you’ll learn what Zipkin is and why it matters in a microservices or a distributed system architecture. Then, following the example application I used for the OpenCensus guide, you’ll learn how to send and view traces in Zipkin. —Author Christian Meléndez
Today, we’ll take a look at just a few of the ways we can improve our .NET application’s performance. And hopefully, you’ll take away something that you can use on your current and future products. —Author Sylvia Fronczak
In this post, I’m going to talk about some reasons why logging alone falls short. I’ll also share some ways you can integrate logging and monitoring so that you can more quickly solve problems that are impacting your customers’ experience. —Author Jean Tunis
Continue by Creating Subheads That Are a Natural Extension of Your Thesis
Some people don’t need to write an outline for a post, but honestly, it never hurt anyone. If you’re just starting out, I recommend laying out your subheads first. There are a few reasons for this.
First, it’s going to reduce your cognitive load while writing. You don’t have to think about your big picture argument while composing—you can focus on making the right word choices and having your sentences flow into one another beautifully, with lots of transitions.
Second, watch what happens when you think of your post as a bulleted or numbered list, under your title and thesis. Here’s the post you’re reading right now, outlined like that:
Imagine if it had instead been something like
It’s not the worst (and the subhead about conclusions is fun). But see how it kind of seems like random points with no logical flow?
Examples
Here are some outlines from this week’s HS posts! We’ll start with a particularly beautiful one. Note how this author also uses parallel structure and repetition of first words to make things doubly clear and easy to follow:
—Author Carlos Schultz
Here’s another example of a post with intuitive-to-follow subheads. Again, parallel structure—using the same verb tense to start each numbered item, in this case—makes an appearance. Note also that this author starts and ends on the same note, giving a feeling of completion for the reader.
—Author Mark Henke
Finish by Telling the Reader Why It Matters
Conclusions are another spot where the reader is expecting you to follow a pattern. If your conclusion lacks a feeling of finality, a certain tone of “we’re done now!,” they’ll leave feeling a little adrift.
So what are the elements of a good conclusion? Well, some might say you should summarize or reiterate your main points, and you can include that if you like. But I think a conclusion should add something new—it should conclude something from what you’ve shared. Since we’ve talked about patterns in this post, a nice one here would be a message of “Now that we’ve learned _________, we can do __________.” And the last element you need is a call to action, a send-off telling them what to do next, or a clever “mic drop” ending. I’ll show you examples of all of these types of endings.
Examples
Here are some HS authors that are doing conclusions right.
This first one starts by telling readers why the post’s information could change their chances for success (read: here’s how the contents of this post can make your life better). And it ends on that “mic drop” note:
Walk the Road
The strategy of thin-slicing your organization gives you a higher than normal chance for success. Hit hard with strong-executing teams. Back them up with the executive leadership on a regular cadence. Train them, invest in them, and these teams will pay dividends. Unlike many softer initiatives, investing your teams in DevOps gives easy ways to get feedback. Your teams will spin up for your feedback loops of operational and business metrics as part of their journey. This will give you insight into their progress and success, pushing forward and pulling out as needed. All that’s left is for you to go out and make it happen. —Author Mark Henke
Up next, we have a conclusion that sums up what the author thinks is most important for the reader to take away, speaking to the big picture. And he ends on a parting challenge to the reader, telling them that they’ll have to consider branching out mentally from relying on comments only. Note the feeling of finality.
Comments Are Just a Tool
In this post, you’ve learned about the types of C# comments, how to use them, and most importantly, why to use them (or not). And while comments do get a bad rap these days, they’re not necessarily evil. Like any other tool, they can be used with wisdom, but also abused. Use the information in this post to help you, but at the end of the day, you’ll have to use your judgment and experience to decide when comments are worth it. —Author Carlos Schultz
And finally, how do we end a tutorial? Those can be harder to wrap up since there’s often no overarching point to drive home. But think about this—why would the reader benefit from learning the program you discussed?
Here’s how one author handled ending a tutorial. He talked about why learning the tech was going to help the reader:
Wrap Up and More Information
Because log4net is so configurable, it helps write your logging code to take advantage of this. Later, you can reconfigure your log outputs without changing the code.
If you want to read more on log4net, Scalyr has more information to help you on your logging journey. Check out this post on getting started quickly logging with C#, this one on logging levels, and this one about what to look for in a logging framework. —Phil Vuollet
Note he ended on a classic content marketing call to action (including bonus internal links)—an encouragement to read more from the blog. You can also link to a product page and encourage the reader to take the next step toward purchase. Take care, though. That last technique should be used as a scalpel, not a hammer, or else you’re not truly doing content marketing.
Stay Tuned for More!
So you’ve got the basics down! You’re writing a clear, no-surprises “this post is about” sentence, you’ve got subheads that are easy to follow and flow well from a bird’s eye perspective, and you know what goes into a conclusion that ends on a satisfying note.
There’s a lot more to chat about, even from an organization perspective.
So stick with me. We’ll be talking more about common writing struggles and how to overcome them. Meanwhile, remember—give the reader what she wants. Follow the structures that will feel right to her. Before you know it, you’ll be a master of delivering the patterns that make your writing satisfying to read.
