Pablo Rivera

Posted on Aug 24, 2017

How to do technical blogging

#blogging #writing #beginners

Quick Summary

In this post, I will show you how to write technical posts. The post outlines the structure of a technical post in detail, provides some useful examples, and some important tips I've learned from experience.

Intro

One of the reasons software developers start blogging is to share their technical knowledge and experiences. What some don't realize is that sharing that technical knowledge is a skill they have to develop on top of basic blogging skills. On this post, I will show you how to write technical posts.

Structure of a technical post

Technical posts are structured differently than regular blog posts. A technical post requires you to provide meta information to the reader because they might decide to implement whatever it is you are explaining. In general, the structure of a technical post is the following:

Headline
Quick Summary
Requirements
Introduction
Multiple step explanation
Examples
Tips
Summary

Let me explain what each of these are.

Headline

The headline in a technical post is very important. It is the part of the content that tells the reader how to do something. That is why a lot of technical headlines use the "how to do X" approach. It is clear, straightforward, and void of any confusing terminology (last thing you want to do is confuse your readers). If you haven't noticed, the title of this post is an implementation of this approach.

Other headline types that are very useful are the following:

Writing a $technology $thing.

Developing with $technology.

Testing $technology with $thing.

Notice that there is a very simple pattern at work. Useful technical headlines tend to start with verbs that provide a quick explanation of what the article is about without the reader having to spend any time reading it.

Quick Summary

The quick summary is not always necessary but it is definitely useful most of the time. It saves reader's time by summarizing in 2-3 sentences what the post is about. Think of the quick summary as a longer kind of sub-headline. It is important to have a relationship between the headline and the quick summary. Where the headline stops, the quick summary should continue. Read the headline and the quick summary of this post and see how smooth the transition is.

Requirements

Requirements are things readers need to have in order to successfully read and apply what the post covers. If you are writing a Python tutorial, then the requirements would be: Python version used, a text editor, etc. Be very specific and include versions when possible. Let me use the example above to show you how it's done:

Requirements:

Python 3.6.1

Text Editor (Vim was used for the examples)

Operating System (Linux, MacOS, Windows) with version information (Ubuntu 16, MacOS 10.12, Windows 10 Professional)

Requirements are important because software varies from version to version and from platform to platform. Clearly specifying what you used lets the reader know if they are equipped to follow along. If not, they can prepare before continuing. This is an area a lot of technical posts fail and leaves the reader to figure out any issues on their own. A good technical writer saves the reader from this frustration.

Introduction

The introduction explains what it is that you will cover on your technical post. It is the place to get anything non-technical out of the way. People often begin including technical details in introductions. This is not a good idea because introductions can be long and not well structured. I hate it when people include obscure technical details in introductions because it immediately throws me off. Here is a good sample introduction:

Python has become the defacto glue language in software development. In it's newest version (3.6.1), the language has evolved into a powerful tool that is easy to pick up. Python is included as a default in most Linux distros, and in MacOS. Such widespread adoption means you will probably not need to install anything in order to run Python on your machine. Follow along as I explain how to use Python's F-Strings in a Linux environment.

Notice how the introduction sets you up for success by providing some light background information without including any technical details that would be necessary later on and have not been previously outlined in the requirements.

Multiple step explanation

This is the area where you explain things in detail. I emphasize multiple steps because breaking things down into smaller parts makes things more manageable for you as a writer and allows readers to quickly pick up where they stop. Multiple steps are also necessary to paint good mental pictures in the minds of readers.

How granular should each step in the explanation be? As granular as possible. Sometimes they may be one sentence long. However, length is less important than scope. Let's talk about scope a little bit.

Scope in technical posts is the same as in programming languages. You have local and global scope. Global scope means that the information being discussed in some place applies to everything else. Local scope means that the information being discussed applies to whatever you are reading right now.

Each step in an explanation has local and global scope. Meaning that the information discussed in each step is important to the step itself first, and second to the general post. But not the other way around. Scope has precedence and it's very important. Having the wrong level of scope in any part of an explanation will confuse the reader.

There are multiple ways to encapsulate scope locally with the help of visual cues. Visual cues are graphic or typographic elements that allow you to let the reader know that everything within specific area is closely related to itself (local scope), but not very related to the global scope. Let me show you an example:

#######
#
# This is a globally encapsulated scope. 
# Note that everything that I write here is assumed to be directly related.
# 
# I wrote this post as a result of a Tweet!
#
######


######
#
# This is a locally encapsulated scope. What I write here is separate from the rest.
#
#  #####
#  #
#  # How are you enjoying this post?
#  #
#  #
#  # #####
#  # #
#  # # Yes, this totally looks like OOP. It is not a coincidence. :)
#  # #
#  # #####
#  # 
#  #####
#
######

One thing I want you to notice is that the deepest level of scope is still related to the other two, but has precedence when it comes to communicating ideas. People tend to read the deepest scope first. This is a very important point. The order people follow when it comes to scope is deepest first. Using the example above, the will tend to read the text above in the following order:

First -> Yes, this totally looks like OOP. It is not a coincidence. :)
Second -> How are you enjoying this post?
Third -> This is a locally encapsulated scope. What I write here is separate from the rest.

In summary, break things down into smaller steps and provide visual cues that inform the reader of scope. Keep things that are locally related to a specific step. When in doubt, break things down and provide visual cues. It is better to have multiple small (micro) steps than a handful of big ones.

Examples

Providing examples is a necessity these days. People will usually skip everything else and go to the examples. That is why it's important to repeat everything in the examples. Yes, that means including the requirements and the multiple step explanations as part of the examples. You will not copy and paste the text into the examples, but you will provide a more concise version of them.

Examples are the most important part of a technical post because people will leverage them to understand whatever it is you are discussing. In fact, how people react to a technical post is directly related to how good the example provided are. The more examples you can provide the better. However, make sure to provide examples in different lengths and types. You don't want to forget including a "Hello, World" example, but you also don't want it to be the only example you include. Using Python's F-Strings, let me show you some examples that you can learn from.

Very simple example used as an introduction:

# python 3.6.1 on MacOS 10.12

# Hello world with F-Strings

name = "World"
print(f"Hello, {name}")

Simple example showcasing some specific technical detail (local scope):

# python 3.6.1 on MacOS 10.12

# Using Python's F-Strings in functions

def hello(name):
    return f"Hello, {name}"

def print_hello(name):
    print(hello(name))

A more complex example would be:

# python 3.6.1 on MacOS 10.12

# Implementing FizzBuzz with Python's F-Strings
# and ternary operators

def fizzbuzz():
  for i in range(1, 101):
      print(f"FizzBuzz with number {i}") if i % 3 == 0 and i % 5 == 0 else None
      print(f"Fizz with number {i}") if i % 3 == 0 else None
      print(f"Buzz with number {i}") if i % 5 == 0 else None
      print(f"Now on number {i}")

The point is to ramp up the complexity of the examples to guide the user on their learning journey. Each of the examples above build on the last one and share one main subject: Python's F-Strings.

Tips

I decided to include some tips I've learned throughout the years. Some of these don't always apply, but are useful to know.

When in doubt, explain. Explaining more is always useful. You can avoid writing walls of text if you use visual cues to provide more in depth explanations. By separating them with visual cues, people can avoid reading them if they quickly understand
Avoid using low contrast colors for visual cues. Light grey font on a dark grey background is not very good. Make it easy to read.
Have multiple people read it. Feedback is important. It's the difference between something that most people understand to something that confuses everybody. It is very easy to write confusing technical posts due to their nature.
KISS. Keep it simple, stupid. Don't include an avalanche of details when a handful will do.
Study highly praised technical posts or documentation. People love to praise Stripe's documentation. Figure out why and apply what you learned to your post.
Use graphics to break down the text. I normally stick to using as little graphics as possible, but they can be useful. It depends on what is being discussed. Most of the time you will have to draw your own graphics. Don't make them too colorful. Stick to 2-5 colors and keep them simple.
Don't put source code in graphics or images. People want to copy and paste the code into their editors.
Allow them to run the code in the article itself. This is not always possible, but useful when so.
Use anchors when possible. People will usually bookmark your page. Providing anchors to specific areas of your post will allow them to bookmark where they stopped reading. Useful with examples.
A light tone is best. Humor is not helpful. Keep the jokes light and out of the source code.

Summary

The summary is the place to add links to additional information, thank those who helped write the post, and add anything that might be useful to the reader. I like to use the following format:

You have now learned about Python's F-Strings. If you'd like to learn more about them, please visit the following links:

- Pep 498, https://www.python.org/dev/peps/pep-0498/

I must thank all of the people who made this post possible. If you need Python development services, please visit yelluw.com and use the contact form to get in touch with me. Feel free to email me at pryelluw@gmail.com with questions.

The format above puts important links related to the article first, all formalities second, and contact information third. I always put the contact information last because people tend to look for it there.

You have now learned how to write technical blog posts. It is something very useful to know because companies tend to hire software developers who can communicate
clearly. It can also be a way to supplement your income. I must thank Stephanie Hurlburt for the idea and support provided. Follow her on Twitter @sehurlburt because she is awesome.

If you need to have technical posts written for you, feel free to contact me through Yelluw's website. You can also email me to pryelluw@gmail.com. You should also follow Yelluw's Twitter account @yelluwmedia and my personal account @pryelluw. I'm also available for short and long term software development contracts. My current focus is on Python, Django, and Javascript.