On Writing Technical Blogs

The Benefits of Learning to Write Well

Writing is humanity’s superpower — when done well, it informs, provokes, and entertains. Perhaps that is why blogging is so popular among programmers. We’re a naturally curious community and sharing knowledge is an integral part of our ethos.

For the reader, the benefits of good writing are obvious. When an author takes the time to prepare a high-quality article, knowledge flows seamlessly from one mind to another. I would argue though that the benefits may be even greater for the writer. Writing a good technical article requires deep research, careful thought, and a significant amount of experimentation. In other words, an author must master their topic before they can write about it.

A rushed article is one that will attract few readers and inform even fewer. So let’s take a couple of minutes to think about what a good article looks like and how we can produce more of them.

Technical Writing is Just Writing

Technical bloggers tend to be focused on the technical side of their work — often at the expense of their writing. Don’t fall into this trap. Technical writing is just writing and all of the standard rules apply. Here are a few of them.

  • Be concise. A short sentence is better than a long one. The same goes for paragraphs. Your goal is to inform your reader, not to overwhelm them. Keep things simple.
  • Have a clear goal. Everything in your article should work towards the same goal. Avoid tangents that are unrelated to your main topic. If the tangents are interesting, save them for a future article.
  • Identify your argument. All good writing, including technical writing, has an argument. The argument may be “this design pattern is useful” or “this feature works in the following way”. If you aren’t sure what your argument is, take a step back and identify it before moving on. Then you can build your article around the argument by presenting appropriate evidence.
  • Grammar, grammar, grammar. Standard grammar and spelling makes for clear and relatable prose. This is important in all writing, including technical writing. It may seem like typos and grammar errors are unimportant, but when a reader spots them it will detract from your message.
  • Edit ruthlessly. The biggest mistake a writer can make is publishing without editing. Your first draft is almost certainly too long, muddled, or riddled with error. Take the time to edit your article and be aggressive as you cut unnecessary material.

As with any kind of writing, technical writing must capture the reader’s attention and keep it. Presenting facts and figures isn’t enough. You need to speak to the reader’s interests and prove that your article is worth their time. Good writing is the best way to do this.

Code Snippets

Technical writing may just be writing, but that doesn’t mean it isn’t unique. If you’re writing about a technical topic then it’s natural to use examples from that domain. For programmers, this means using code snippets. Of course, writing code is itself another kind of writing! That means that many of our earlier rules still apply.

As you are presenting a code snippet, try to empathize with your reader. Is your snippet clear? Does it address your topic directly? Does it introduce unnecessary complexity? Let’s look at an example. Imagine that you are trying to explain how the map function works in Python and you draft the following code snippet.

This code works, and it does indeed make use of map, but it’s otherwise unintelligible. The function and parameter names are nonsense, the use of a lambda function is unnecessarily complicated, and the snippet uses a first-class function for no particular reason. The whole point is to teach your reader about the map function — don’t confuse them with related but tangential topics. Here is a better version.

In this version, the intent is much clearer. The map function is the centerpiece of the snippet, the variable names are meaningful, and there are no distracting tangents. Resist the temptation to use advanced functionality when it’s not necessary. Your goal should be to draft simple and direct examples that aren’t muddied by extraneous content.

Sometimes though, clear code isn’t enough. Your snippets also need to be interesting. For example, take the below snippet, which illustrates the concept of class inheritance.

There is nothing inherently wrong with this snippet — it is clear, concise, and focuses on the topic we’re interested in. The only problem is that it’s not particularly engaging.The Car example is widely used and feels a bit uninspired. Let’s try again.

The Receipt example may be mundane, but it feels like something that you might actually do as a developer. In that sense, it’s much more relevant than the Car example. The subject matter may be boring, but at least it’s real, and therefore relatable.

Relevance is one way to help your readers connect with your snippets, but it’s not the only way. Don’t be afraid to use a little whimsy. Why write about Vehicles and Animals when you could write about Starships and Dinosaurs instead? Use your imagination! Choosing engaging and original examples for your code snippets will keep your reader focused and interested.

Presentation

Now you have a well-written article with thoughtful and engaging code snippets, but there is still one way that you can tank the whole thing: poor presentation. The visual design of your article provides structure and governs how topics flow into one another. If you don’t pay attention, your words could be overshadowed by clunky design.

Most blogging platforms have ample functionality for design, whether it’s italics, code highlighting, bullets, subheadings, or images. Make use of this functionality — it’s there to help you design a visually appealing article that draws the reader in rather than pushing them away.

Good visual design is clean and functional, with a dash of style. Per usual though, our principle of simplicity and concision applies. There is no need to litter your article with unnecessary images or charts. A little bit goes a long way. And when you do decide to use non-text elements, do so thoughtfully. Visual elements are as much a part of your article as the text, and should show equal care. Consider the below code snippet for a notional article about searching algorithms.

def binary_search(items, target):
left = 0
right = len(items) - 1

while left <= right:
mid = (left + right) // 2
if items[mid] == target:
return True
if items[mid] > target:
right = mid - 1
else:
left = mid + 1
return False
company_languages = ["C++", "Clojure", "JavaScript", "Python", "Ruby"]candidate_language = "Python"if binary_search(company_languages, candidate_language):
print(f"We use {candidate_language} too!")
else:
print(f"Are you willing to learn another language?")

Not very appealing is it? The content is fine, but the lack of syntax highlighting is distracting and bland.

Much better! It’s a small change, but it makes for a more enjoyable visual experience. It also shows that you’re taking the time to consider the details. And if you considered the details with a simple thing like syntax highlighting, then the reader will know that you considered details in the content of your article as well.

Why Write?

Writing is hard, but it’s also joyful. For a writer, it can be immensely satisfying to put your thoughts to paper. Not only are you likely to learn something new in the process, but your reader might learn something new too. And the more you write, the more joy you will derive.

For technical bloggers, imposter syndrome is always a concern. No matter how much you learn, it will always seem like someone else knows more. Remember though, you’re not writing a textbook. You’re writing for yourself. You should strive to be accurate, and do sufficient research and testing to confirm as much, but at the end of the day you’re still an amateur. And that’s OK!

Good writing is as much about learning as it is about teaching. If you’re curious about a topic, or even confused by it, the best thing you can do is write about it. The process will force you to learn along the way.

As with coding, or data, or engineering, writing is a skill that takes practice. But quantity does not necessarily mean quality. Don’t aim to be prolific — aim to be thoughtful. All writing, whether technical or otherwise, is deeply personal. It says something to the world about who you are, and if you take the time to do it right, readers will take notice.

Writer | Developer

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store