How To Write Technical Blog Posts 2023
I love technical blog posts, especially ones that take you through the process of building an application from start to finish. After reading thousands of tech blog posts and writing many of them myself, I decided it was time to share my workflow in the hopes of helping others who are building amazing things blog more easily and more often. The specific tools used in this workflow are based on Mac OSX, but the concepts can be applied to any toolchain. Check out AlternativeTo.net to find similar applications for your operating system.
Use natural programming
When I write a tech blog post, the goal is to create something that saves readers time and sparks new ideas. Before starting, I thought about these two questions:
What do readers get when they finish reading my article? Answers should include time saved for the reader and/or new ideas generated.
What makes my content different from the thousands of other posts addressing similar issues? Wouldn’t it be easier to point directly to someone else’s post? Sometimes all you need is a link to another article with some added context.
If I can come up with acceptable answers to these questions, that’s fine. The topic is listed on Lists. For me, the “list” is an Evernote note called “Writing Ideas.” Right now, this is a simple list, but I plan to categorize these at some point, probably using a tag-based system. For example, some ideas would be better placed on my personal blog than on Medium or Google+, and some ideas should be on SendGrid’s blog.
Once I decided to extend the topic into blog posts, the workflow started. For my workflow, I prefer a modified version of the 5 phases of the GTD Natural Planning Model (NPM), which I will elaborate on now.
Define purpose
While I’m sure I’m motivated enough to create a blog post, I find it helpful to delve into the following questions: Why are we (me) doing this?
I usually define “we” as the stakeholders, which include your audience (be specific), your company (what do they expect?), and possibly co-authors.
For example, I wrote this blog post to help developers turn their software projects into blog posts that help other developers. This purpose ties in with one of my purposes as a resident hacker at SendGrid, which is to improve and inspire the lives of developers internally and externally.
Confirm goals and measurements
Now it’s time to visualize what the finished look will look 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’s quantify by thinking about how to measure success. Is it 1,000,000 unique visitors? 30 downloads? 100 retweets? 10 forks? Generate enough donations or ad revenue for beer (preferably an IPA)?
Be sure to consider your start and end dates.
Brainstorming possibilities
Once a topic is settled, I find mind maps to be the best tool for expanding ideas. Note that in many cases, after spending a few minutes mind mapping an idea, the best conclusion may be to drop the idea.
While I prefer to use a mind map for this step, you may prefer index cards, paper, a whiteboard, or an outline. Remember, the key here is to let your ideas flow without censorship. Try not to organize your thoughts at this point. Just do a brainstorm focused on the topic.
For digital mind mapping, my current tools of choice are MindNode on Mac OS X and iThoughts on iOS. I’m not sure what the benefits are on Android, so any suggestions in the comments are greatly appreciated.
In-depth study of topics
I like to include this step after brainstorming so I don’t pollute the creative process with outside ideas.
Now that you’ve put some of your original ideas on paper, it’s time to find out what knowledge you’ve discovered. I recommend that you a) set the time for this step, and b) use resources other than a simple Google search.
For each blog post, I like to create an Evernote notebook to store the research, but you can also use the research feature in Scrivener, which allows you to keep all the information related to your blogging project in one place.
Plan your blog posts
Now, it’s time to organize your thoughts and research, and that’s where Scrivener comes into play.
At this point, we translate our purpose, goals, brainstorming, and research into an outline. I like to use Scrivener’s corkboard mode for this.
Determine next steps
For each item in the outline, think of any action items you need to accomplish in addition to writing. Items like getting information from other people, buying assets, or queuing editors/testers are a few examples.
In my case, these tasks are stored in a project in OmniFocus created specifically for this blog post. Each next action has a name, defined as if I were outsourcing the task, a GTD-style context, and an estimated duration. Alternatively, I can add start and/or due dates.
Write it now
When writing blog posts, my tool/language of choice is MultiMarkdown.
I suggest you make some changes to Scrivener to make writing in MultiMarkdown more enjoyable. First, go to Scriverner->Preferenes->Formatting and change the font, remove indentation and uncheck underline links.
Then go to the Corrections tab and uncheck Use smart quotes and Auto-detect URLs.
To preview how your MultiMarkdown will look after formatting, I use Marked. Just drag items onto the marker icon and you’re ready to go. The preview will automatically update as Scrivener autosaves.
You will most likely include code, images and possibly videos in your blog posts. I like to use GithubGist for code to be displayed inline, images are usually stored locally, and videos are usually stored on YouTube or Vimeo.
Publish your Post
Once the article is finished in Scrivener, the next step is to export to TextMate. This is done by choosing File->Compile and choosing plain text as the output and saving it with a .md extension.
In TextMate, I preview Markdown and make final edits. I recommend you to use Fletcher’s Markdown package. At this point, you are ready to hand off to your editor or publish to the final editor, your audience.
If your blog post is a tutorial, I suggest you get another developer to run it and try to replicate your results, providing feedback along the way. Make it a habit to do the same to others.
Most of the time I publish using WordPress, in those cases I export to HTML and paste into an HTML editor. Alternatively, you can try the WordPress WP-Markdown plugin.
Promote post
Now that your blog post is live, it’s time to let the world know. Here are some ideas to get you going:
Let your colleagues know about the position and encourage them to interact
Post to the following social networking sites (those that make sense for your particular post):
Twitter – use hashtags sparingly and refer to related accounts
Google+ – be sure to share with relevant communities
Dzone – complete the submission form
Hacker News – Be ready to interact if the community starts commenting on your posts
Reddit – Choosing the right sub-reddit
Slashdot – Enjoy Fire Hose
People you know via email (or otherwise contact) would definitely benefit from the content
Post to relevant groups in the company’s internal chat system
Add links to your company documents and/or website
Included in your company newsletter
If it’s posted on your company blog, please link from your own personal blog parting miss.
I recognize that this process may seem like overkill at first but considering the time it takes to automate the workflow once you make the process a habit and start automating the workflow, the time investment will pay off enormously in the end.
