Unpacking the Technical Blog Post

Technical blog posts are a fantastic place to share knowledge and lessons learned. They're also a powerful tool for building visibility and (in the right setting) attracting customers. While they share DNA with other types of technical writing, the marketing opportunities surrounding technical posts make them a distinct form.

Have a goal

Before writing anything, get clear on the goal. Some of the motivation behind a technical post may be altruistic (sharing knowledge, advancing a theory, challenging assumptions, or otherwise joining in a broader community conversation), but even altruism can bring positive attention to the author. There's likely some goal in the mix, and implicitly or otherwise it likely comes down to:

1. Selling something. A technical post may be a good opportunity to introduce the audience to products, services, mailing lists, or even open job listings.
2. Building visibility. Even a "sales-less" blog can raise the profile of the individual or organization that published it.

These goals will likely stretch beyond a single post. A campaign to attract new sign-ups for a web application may be supported by a series of posts that all aim at the same segment of prospective users.

Whatever the goal, it will inform the full cycle of the technical blog post---from who it's written for, to what it's written about, to how it's published and promoted.

For now the thing to keep in mind is that the post does have a goal, that the goal likely fits into a broader campaign, and that the goal is central to the post's construction.

Identify an audience

The audience for any given technical topic will be much smaller than the Internet-going population as a whole. But there are technical audiences, and then there are technical audiences. Depending on the post's goals, it may aim to reach beginners, experts, kindred spirits, ideological opposites, or some combination of all four.

Different audiences come with conflicting goals. Writing aimed at beginners will alienate advanced readers, while technical minutiae presented without background or context will alienate almost everyone else. Two good questions for finding the middle ground are:

1. Will the audience be generally familiar with foundational concepts? If the post references algorithms, standards, or practices in widespread use, it may be safe to leave them at a name and a link. If they're more obscure (at least for the audience at hand) they may benefit from more explanation in line.
2. How much familiarity will the reader have with the specifics? A new technology (or less experienced audience) will require more explanation than a familiar one applied in a new way. The same goes for ideas and references that aren't yet part of industry canon.

Just as readers arrive with different levels of experience, they also come from different points of view. A post that challenges accepted dogma will need to offer more evidence than one built on existing beliefs.

No post will resonate with very reader, and that's OK. There's no such thing as one-size-fits-all content, and no amount of writing and re-writing will change that. The game is to identify a target audience and make good use of their time.

Pick a topic that matters

With the goal established and the audience defined, the next step is to winnow down a long list of potential topics to the ones that really matter.

This shouldn't be a spur-of-the-moment decision. Developers know that there's an art to not writing software, and the same is true of blogging. Ideas are cheap, and skipping over so-so ideas early means more time for developing the really good ones.

Keep a list of ideas

The first step in prioritizing what to write about is to list out all the possibilities. Do it in a spreadsheet, text file, or the nearest note-taking app, but do it in writing---it's a list that will grow over time.

Once it's filled out, this list will likely include ideas for posts that:

1. Demonstrate a technique
2. Announce new projects, products, or features
3. Answer burning questions
4. Challenge assumptions
5. Share lessons

This list is also a good place to store new ideas that turn up while writing. Each post gets to make exactly one point. If new ones pop up and they're worth following up on, they'll make great posts of their own.

Prioritize the idea list

It's easier to generate ideas than to pare them back down. The real art is in ruling out possible posts to get down to the ones that will have a genuine impact.

As a starting place, reflect on how each topic or idea might be received:

1. What will the reader learn?
2. How will the reader's perception of [tool|technology|etc] change?

If the answers aren't clear and compelling, move on. Time is precious, and a reader who isn't finding value won't stick around.

A second filter to apply is novelty. It's fine to overlap with other writing on the Internet, but a post that doesn't offer a fresh perspective, new idea, or meaningful contribution beyond existing content is a post that doesn't need to be written.

Finally, consider how receptive the audience will (or won't) be to a post's central theme. There's an audience for every position, and most technical content isn't overly bombastic or provocative, But when you're representing a broader organization or brand, the old adage that "any press is good press" is one to handle with care.

Write the post

Find a voice

Technical writing prizes clarity over creativity and drama. There's still room to adjust tone to better connect with an audience, however, and particularly in the less-formal setting of a blog.

For instance:

• a conversational tone can help invite an unsure reader into a how-to article
• a more assertive posture may create an air of authority for press releases or feature announcements
• a challenging tone may help spark debate (and a more conciliatory tone may help disarm it)

Next, assign the narrator's point of view. The easiest way to do this is through pronouns:

• Singular first-person pronouns (I, me) underscore accountability and may help an audience relate to a post-mortem or mea culpa.
• First-plural pronouns (we, us) replace a singular author with a collective---useful for representing an organization's general opinions or sharing its work.
• Avoiding pronouns keeps the narrator out of things and may reduce the emotion out of the pieces at large.

Different voices may be appropriate in different situations. The key is to be consistent. If an existing style guide is available for the publication, blog, or organization in question, use that. If it isn't, a little time invested in a lightweight approximation will save time in the long run. Are pronouns acceptable? Passive voice? Adverbs?

Answer those questions up front, and the details will follow.

Tell a story

Our brains come wired to appreciate a good story. A little emotion and shared humanity improve learning and retention over an impartial, procedural format, and increase the odds that a technical blog post will actually be read.

Translating technical content into narrative form follows a fairly straightforward formula. Instead of straightforward exposition, the narrative version will build around:

• a hero (who is it?)
• a quest (what is the hero out to do?)
• obstacles (what must the hero must overcome?)
• a climax (what is the final obstacle?)
• a reward (has the hero grown? has the world changed?)

While the hero could be an operations team (in a post-mortem), a product manager (product release), or a software developer (a bug hunt), it may also be the reader herself. Tutorials and how-to articles often build around this structure:

By reading this post (quest), you (hero) will encounter the challenges (obstacles) on the way to a solution (climax) that you can use to accomplish some task (reward).

Whoever it features, the story should always be aligned to the post's target audience. "Middle-manager uses technology to slay recalcitrant corporate bureaucracy" may draw sympathy for a general audience, but it likely won't inspire readers drawn by a headline about a cutting-edge development framework.

Write the hook

A blog post's hook is simply a reason to keep reading. In one sentence (two at the most) it sets the stage and makes a promise about what's yet to come. It should answer:

1. What's the story? This may be explicit (as in a news lede), implicit (a destination revealed with little detail about the journey) or somewhere in between. A good hook will tease the story without giving everything away, piquing a reader's curiosity and drawing them deeper into the post.
2. What's the benefit? Make the post's "value" concrete by telling the reader what (beyond a good story) they will gain by reading on.

The hook comes first. Write it last. Better yet, find some collaborators to toss ideas around and write several versions together. Settle on the ones that feel most compelling. After the article's headline and marketing metadata, the hook is the next most important step for drawing a reader in. It's worth the time it takes to get it right.

Content: words, sentences, and examples

"Content is king." What was true to Bill Gates in the mid-90s is no less true today, and no amount of marketing will make a lousy post worth reading. It starts with a clear goal (check), a great idea (yep), and a (hopefully) receptive audience.

With technical content, the usual rules of good writing still apply. But the challenge of clear, economical writing is compounded by the challenge of creating clear, economical supporting examples that appeal to a wide range of audiences and individual learning styles.

1. Diagrams and illustrations can help a reader orient themselves within a multi-step discussion or workflow. They're most useful when simple and clearly labeled: a diagram that attempts too much may be better off as a standalone chart or infographic.
2. Code samples translate abstractions into concrete terms. Since they're easiest to understand when focused on a single idea, it's usually more helpful to construct a post's examples in isolation than to try explaining their place within more complicated (and likely unfamiliar) real-world systems.
3. Data aggregations, analyses, and visualizations are much more helpful than raw datasets. Simpler tables, charts, and algorithms are easier to understand and more likely to be used.

All examples, regardless of format, should include brief captions and links to relevant external references (data sets, source code, and so on).

Different posts will follow different conventions, but they should all treat the audience's time with the highest respect. The audience is filled with busy people who have other places to be. The central idea needs to be clear. Details need to clearly support it.

Remember: a post gets exactly one call to action, and it belongs near the end. A reader will only see it if they have a reason to keep reading.

Wrap it all up

A post's conclusion is a chance to restate key points and revisit the hook's promise. Did the post deliver?

Since it did, there is only one thing left to do. Make the ask. The post had a goal. Whether it was to sell something, build visibility, or just contribute to the broader body of knowledge, it's time to request something from the reader in return. That's the call to action (CTA), and there should only be one.

1. Hire me (us)
2. Buy my (our) product or services
3. Follow me (us) and/or share this post on social media
4. Review our job listing
5. ...and so on.

Make this clear, keep it brief, and put it in context of the rest of the post.

• Like what you've read? Signing up for our newsletter is the best way to discover great new posts like this one.
• Want to stay in the loop? Follow us on social media for ongoing coverage.
• These are the sorts of problems we solve every day. Did we mention that we're hiring?

With this, the post has come full circle. After drawing an interested audience and giving them a unique insight, feature, or story, the CTA makes good on the goal that drove the post in the first place.

Publish and promote

Professional marketers spend their days figuring out how to reach potential customers with the right message at the right time. It's a fuzzy problem with a vast search space and very few clear answers, but a technical blog post can get pretty far by focusing in on three things:

1. The channels that draw readers to the post
2. The conversion from the post's CTA
3. The analytics that connect channels to conversions

In other words: how do people find the post? is the post achieving its goal? and how do we know?

Marketing channels

Unless a post has the benefit of an established audience (via a newsletter, for instance) or a non-trivial marketing budget, readers will likely find it through one of three channels:

1. "Owned" media - via social media (Twitter, LinkedIn, etc) or forum (Hacker news, reddit) posts from accounts managed by the post's author. This channel depends on interesting headlines and compelling post previews.
2. "Earned" media - via shares or syndication from other social accounts
3. Search engines - via longer-run Search Engine Optimization (SEO) campaigns

Channel strategies may overlap, but don't count on it. Search engine rankings take time and careful keyword planning; social posts may disregard keywords entirely while presenting enticing, clickable headlines headline. "Evergreen" content will rarely be able to ride a wave of current events, but more topical content may quickly lose relevance.

The key is to pick a single channel and put the time in to develop it. While every channel has its strengths and weaknesses, steady ongoing efforts to attract followers (owned media); build relationships (earned media); and build credibility (search engines) will help them reach their full potential. Whatever the focus, one reliable hit will always be better than three or four near misses.

Finally, though additional channels (e.g. emails/newsletters, paid advertising, syndication, etc) may help boost reach in a more mature marketing campaign, they will only add---not replace---the big three.

Conversions

For the purpose of the post's goal, a conversion is a user answering the CTA.

For the purpose of tuning the post towards that goal, it's helpful to think of the post as its own little funnel. Multiple "conversions" lead up to the CTA, as a reader:

• finds the post
• finishes reading it

A post that readers aren't finding, or a channel that's underperforming, implies low visibility, a lack of interest, or both. It may be possible to tweak the post's preview (title, description, and opengraph/structured data) to improve discoverability. It may also just be a miss on audience, topic, or channel. These things happen. Time to take a different swing.

If readers aren't reaching the entire post, it may be down to a perceived lack of value---or to the promise being adequately fulfilled before the end. This is an easier problem than getting people in the door in the first place, but no less crippling to the blog post's goals.

Instrumentation and analytics

Google analytics' defaults will go pretty far, especially if inbound links include sensible utm parameters. The channel breakout will show where visitors are arriving from; with an instrumented call to action (if it's a form, button, or anything other than a link) it's a small step to track conversions the whole way through the campaign.

Conclusion

That's it: from ideation to promotion, a comprehensive look at crafting interesting, insightful technical blog posts. And don't forget to share a link as soon as that post's finished!