This post originally appeared on The Quick Left Blog
Part 2: Write
In this three part series, we’re looking at some of the best ways to get into a good flow as a technical blogger. In the first part, we talked about some initial steps you can take to get psyched up when figuring out how to write a technical blog post. In this, the second part of of the series, we’ll talk about how to do the actual writing itself. We’ll explor some effective structures you can use to organize your posts, thoughts about the creative process of writing, and how to make sure your content is as good as it can be.
Define Your Structure
So you’ve got a topic, you’ve identified a long-tail keyword, and you’re ready to start writing. You put your text editor in distraction-free mode, don your noise-canceling headphones, and get ready to dig in. But where to begin?
I recommend treating your first session on a given post as a scaffolding-building session. Don’t expect to get into details. Forget about jokes and memes. Just sketch an outline of what you want to write about.
There are quite a few good ways to structure a blog post. You don’t have to reinvent the wheel. Just pick one of these basic approaches, and it should get you where you need to go.
The List
You know what I’m talking about. Titles like Five Ruby Methods You Should Be Using are gold. Potential readers know titles like this are a cheap shot, but they can’t resist clicking the link anyway. That’s why it’s called click-bait.
If you’re writing this kind of post, the structure is obvious: write an intro and a conclusion, and slap the five Ruby methods and their explanations in the middle.
The How-To
So much of our industry is about learning new technologies and new ways to do things. Developers need to understand “how to do X” every single day. When they google for it, they will probably type “how to…” If your post begins with those words, perhaps it will be the one they find and read.
Writing a how-to article is a little more complex than doing a list. I usually break it down like this:
1 2 3 4 5 6 | |
I used this structure in my Wrapping Your API In A Ruby Gem post, and got a lot of great feedback from readers.
The (Five) Paragraph Essay
If you’re writing an opinion or agile process piece, the basic Five-paragraph essay style is a great way to organize your thoughts. If you went to high school, you’re probably familiar with this layout, so it can be a comfortable choice to reach for. To write an essay think about how you’ll introduce your topic and assert a thesis. Next, prove your point with supporting arguments. Finally, summarize and reiterate your argument in the conclusion. Your outline will look something like this:
1 2 3 4 5 | |
The Well-Actually
At Quick Left, we do a lot of joking about being a neckbeard. There are a lot of smart people that work here, and more often than not, they have strong opinions about how to do things. Sometimes when one person begins to make a statement, an opinionated colleague will correct them with a sentence that begins with “well actually…”
“Well actually” is a great phrase, full of tension. In fact, you can build an entire blog post around the drama of this tension. Some of the most interesting articles I read are ones that follow what my mentor Jeff Casimir called “the hero’s journey”.
The basic breakdown of the hero’s journey story goes like this. First, you write about “I always thought that foo worked like bar”, or “I’ve always solved foo by doing bar”. Then you move on to say, “one day, I decided to solve foo by using baz instead”. Finally, you wrap the whole thing up with “but it turns out that the correct solution is neither bar nor baz, but qux”. This is your “well actually moment”.
These kinds of posts can be fascinating to read because they follow a story arc, and they provide more suspense than you get in flat structures like lists and how-tos.
Interlude: Let It Simmer
Deciding on a topic, generating a long-tail keyword, and sketching out your basic structure is pretty good for a first day’s work on a post. At this point, I usually like to leave the post alone for a while and let it simmer. I’ve found that when I take a break and give it a little space, my subconscious gets to work on exploring the main points I’ve set out for myself. When I come back, I find I have plenty of ideas of what to say. When I take some space in between writing sessions, the resulting post tends to be a lot richer than when I force my way through in a single sitting.
Fill In The Details
After you’ve taken a bit of a break and you’re ready to come back to your writing, it’s time to actually do the hard part. At this point, I typically feel that I’d like to do anything but sit down at the keyboard. I can think of a million distractions: “I’ll start writing right after I go get a pumpkin spice latte”, “just as soon as I send this email”, or “I think I’ll check Reddit first”. All of these impulses are what a mentor of mine once called anything to avoid buckling down.
So how do we overcome the feeling of anything to avoid buckling down? My favorite way to deal with this problem is to set up a ritual. I won’t get into the details of what mine entails, but here are some things that can be helpful: put on a specific kind of music, remove social media, email, and chat distractions, set up a different mode in your text editor, drink a certain coffee beverage. You can get even more superstitious if you want to. But the basic idea is that by identifying a series of things you do before you write, you can train your brain to get “in the zone”.
Once you’ve gotten in the zone (however it is that you do that), just start writing. You know the phrase “genius is 1% inspiration and 99% perspiration”? This step - filling in the details - is the perspiration part.
The key thing at this stage is to let yourself get into flow state. As you start to express an idea, you’ll be tempted to stop and think “is that good enough”, “is that really accurate”, or “could I have worded that better?” I recommend just letting it come as it will, and put off the judgements for later. Interrupting yourself to evaluate your writing disrupts your flow. If you’re a programmer, think of it as a TDD exercise: first make the idea come out, then refactor.
Often times, you’ll have to complete a couple of sessions like this before you get through your entire structure and have a complete first draft. Each time you sit down to write about it, you have to get back into the flow. Just follow your ritual and keep working. You’ll be through it before you know it.
Write A Conclusion
There’s a bit of an art to writing a conclusion section. On one hand, you want to reiterate and summarize the high-level concepts involved with what you’ve been talking about. On the other, you want to encourage the reader to think about the wider implications of the subject. How can it be applied to other situations? How can what you’ve been talking about be extended illuminate a higher level of understanding? For example, if you were writing about Stripe integration, maybe talk about how your post fits in the broader context of e-commerce.
The conclusion is also a great place to encourage people to take some sort of action on what they’ve learned. Whoever’s hosting your blog post would probably like to have the readers interact with their website. You can push them to do this by linking them to relevant content elsewhere in the site. Or you can use a P.S. section encouraging them to leave a comment on your post.
Proofread It (Twice)
Once you’ve completed your conclusion, your first draft is done. Take another break and get some space from the post. Shift your mindset from “getting stuff done” to “let’s clean this up” instead.
Remember above when I suggested you put off judging or evaluating your work? Now’s the time to invite that impulse back in. It’s time for everyone’s least favorite part of writing: proofreading. You need to do it. Read through what you’ve written and make any changes that suggest themselves. Then read it aloud and see how it sounds. Make more changes. Pretend that you are a member of your target audience and read it from their point of view.
The more times you repeat this process, the more clear and understandable your writing will be. Aim for brevity and precision. Long sentences are hard to understand. Only write as much as you need to to get your point across, cutting out extraneous words and explanations and really tightening up your word choices.
Ask For Review
It’s a really good idea to get another set of eyes on your writing. If you’re lucky enough to have an editor, they will give you great ideas for improving your phrasing, word choice, and structure. If not, reach out to your peers to see if any of them are willing to help you improve your work. Especially target those you think already know the ins and outs how to write a technical blog post. The more people you can get to check your work before you release it to the world, the better.
You can also ask someone in the role you’re writing for to review it. If there’s nobody on your team in that role, try reaching out to a popular influencer on Twitter or elsewhere on the web. In fact, this is also a good thing to consider doing for promotional purposes. Reaching out to major influencers early and gathering their feedback on your topic might lead to them sharing your content, which will dramatically improve your traffic.
Once you’ve solicited some help, take your reviewers’ advice to heart. You don’t have to incorporate every single change they suggest, but try to keep in mind that they’re not out to criticize you personally. They’re trying to help you, and the places they have trouble understanding your language are good spots to polish up the way you present your ideas.
Once you’re done proofreading, editing, and making changes from reviewer comments, you’re almost done writing. But first, there’s just one more thing. Proofread it again. I’m not kidding :)
Wrapping Up
Even if you know what you want to write about, the process of actually getting the words down can be hard if you haven’t done a lot of writing in the past. In this post, we’ve looked at some cookie-cutter structures you can use to scaffold your post, the importance of giving yourself some space between writing sessions, and tips for proofreading.
Stay tuned for the third and final part of this series, where we’ll explore how to draw more visitors to your post using SEO best practices and how to promote your writing on social media for the most benefit. See you then!