On Writing Technical Blogs

The Benefits of Learning to Write Well

Photo by Liviu C. on Unsplash

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…