Curious how to write technical blog posts? We've got you covered.
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.
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:
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.
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.
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 into one of my purposes at SendGrid as the Hacker in Residence, which is to improve and inspire developers' lives, both internally and externally.
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)?
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:
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.
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:
Once you organize the index cards you can jump to outline mode for further refinement:
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.
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.
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.
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.
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 :)
