How I Write Technical Blog Posts


Posted on

I love technical blog posts, especially those that can take you through the entire process of building an app, A to Z. After reading thousands of technical blog posts and writing many myself, I’ve decided that it’s time to share a workflow that I hope will help those who are creating amazing things to blog more easily and often. The specific tools utilized in this workflow are Mac OSX based, but the concepts can be applied to any toolchain. Check out AlternativeTo.net to find similar apps for your OS.

Use the Natural Planning Method

When I write a technical blog post, the goal is to create something that saves the reader time and inspires new ideas. Before I get started, I ponder these 2 questions:

  1. When the reader finishes reading my post, what will they have gained? The answer should involve saved time and/or new ideas generated for the reader.
  2. What makes my content different than the thousands of other posts out there solving similar problems? Is it easier to just point to someone else’s post? Sometimes, all you need is a link to another post with some context added in.

If I can come up with acceptable answers to those questions, then it’s a go. The topic goes on “the list.” For me “the list” is an Evernote note called “Writing Ideas.” Right now, it’s a simple list, but I plan to categorize these at some point, probably with a tag-based system. For example, some ideas are better suited on my personal blog versus medium or Google+, and yet others should live here on SendGrid’s blog.

Once I’ve determined I will expand the topic into a blog post, the workflow begins. For my workflow, I prefer a modified version of the 5 phases of the GTD natural planning model (NPM) which I will now elaborate on.

Define the Purpose

Though I’ve already decided that there is enough motivation to create the blog post, I find it helpful to dig deeper into the following question: Why are we (am I) doing this?

I typically define “we” as the stakeholders, which include your audience (be sure to get specific), your company (what do they expect to gain?), and possibly co-authors.

For example, my purpose for writing this blog post is to help developers convert their software projects into blog posts that will in turn help other developers. This purpose ties in to one of my purposes at SendGrid as the Hacker in Residence, which is to improve and inspire developers’ lives, both internally and externally.

Acknowledge Objectives and Measurements

Now it’s time to visualize what done looks like. Think of it as defining your scope of work. What does success look like? What exactly do I want the reader to learn?

Let us quantify by thinking about how success is measured. Is it 1,000,000 unique visitors? 30 downloads? 100 retweets? 10 forks? Generating enough donations or ad revenue for a beer (preferably an IPA)?

Be sure to account for your start and end dates.

Brainstorm the Possibilities

Once the topic is decided, I find that a mind map is the best tool to expand upon the idea. Note that in many cases, after spending a few minutes mind mapping an idea, the best conclusion may be to discard the idea.

Though I prefer to use mind mapping for this step, you might prefer index cards, paper, a white board or outlines. Remember, the key here is to let your thoughts go wild without censor. Try not to structure your ideas at this point. Just do a brain dump focusing on the topic.

For digital mind mapping, my current tool of choice is MindNode on Mac OS X and iThoughts on iOS. I’m not sure what’s good on Android, so I’d appreciate your suggestions in the comments.

Here is an example using MindNode that I used when brainstorming for this post:

Brainstorm the post

Research Deeper into the Topic

I like to include this step after the brainstorm, so I don’t pollute the creative process with external ideas.

Now that you have some of your own original ideas out on paper, it’s time to find out what knowledge has been already uncovered. I suggest that you a) timebox this step and b) use resources beyond simple Google searches.

For each blog post, I like to create an Evernote notebook to store the research results, but you can also use the Research feature in Scrivener which allows you to keep all the information related to your blog project in one place.

Plan Your Blog Post

Now, it’s time to organize your thoughts and research, here is where Scrivener comes into play.

At this point, we take our purpose, objectives, brainstorm, and research and transform that information into an outline. I like using Scrivener’s corkboard mode for this. Here is an example of what that looks like in Scivener:

Planning the post

Once you organize the index cards you can jump to outline mode for further refinement:

Versions of blog post

Identify Next Actions

For each item in the outline, think of any action items, besides writing, that you need to accomplish. Items such as obtaining information from other people, purchasing assets or lining up editors/testers are a few examples.

In my case, these tasks are stored in OmniFocus within a project created specifically for this blog post. Each next action has a name that is defined as if I were outsourcing the task, a GTD style context and an estimated duration. Optionally, I may add a start and/or due date.

Now Write It

My tool/language of choice when writing blog posts is MultiMarkdown.

There are a couple of changes I recommend that you make to Scrivener to make writing in MultiMarkdown more pleasant. First, go into Scriverner->Preferenes->Formatting and change your font, remove the indentation and uncheck Underline links.

Edit the post

Then head over to the Corrections tab and uncheck Use smart quotes and Automatically detect web addresses.

For previewing what your MultiMarkdown will look like when formatted, I use Marked. Simply drag the project onto the Marked icon and you are in business. The preview will auto-update as Scrivener auto-saves.

Most likely you will include code, images and possibly video in your blog post. I like to use GithubGist for code that is to be displayed inline, images are usually stored locally and videos on YouTube or Vimeo.

Publish the Post

Once I’ve completed the article in Scrivener, the next step is an export into TextMate. This is done by selecting File->Compile and choosing plain text as the output, saved with a .md extension.

In TextMate I preview the Markdown and make my final edits. I suggest you use Fletcher’s Markdown bundle. At this point you are ready to turn over to your editor or publish to the ultimate editor, your audience.

If your blog post is a tutorial, I suggest you have another developer run through and try to duplicate your results, providing feedback along the way. Get into the habit of doing this for others as well.

Most of the time I use WordPress to publish, in those instances, I’ll export to HTML and paste into the HTML editor. Alternatively, you can try the WordPress WP-Markdown plugin.

Promote the Post

Now that your blog post is published, it’s time to let the world about it. Here are a few ideas to get you going:

  • Let your co-workers know about the post and encourage them to interact
  • Post to the following social websites (those that make sense for your particular post):
    • Twitter – use hashtags sparingly and mention relevant accounts
    • Google+ – be sure to share with the relevant community
    • Dzone – fill in the submission form completely
    • Hacker News – be ready to interact if the community starts commenting on your post
    • Reddit – choose the appropriate sub-reddit
    • Slashdot – enjoy the firehose :)
  • Email (or otherwise contact) people who you know will definitely benefit from the content
  • Post to the relevant groups in your internal company chat systems
  • Add a link from your company’s documentation and/or website
  • Include in your company’s newsletter
  • Link from your own personal blog if it’s published on your company blog

Parting Thoughts

I recognize that this process may seem to be a bit overkill at first glance, but consider that once you turn process to habit and begin to automate the time spent implementing your workflow, that investment of time will pay big dividends eventually.

Whatever workflow you choose to implement, take the time to document it. Bonus points if you share that process :)

Happy Hacking!


Elmer Thomas is SendGrid's Hacker in Residence. His mission is to help SendGrid live up to its slogan: "Email Delivery. Simplified" by improving the lives of developers, both internally and externally. Via all sorts of hackery, of course. Follow his exploits on Twitter and GitHub.

Elmer Thomas on Twitter
Have thoughts on this post?
Chat with us about it on Twitter and Google+