Updated date:

How to Write a Good Technical Article


Technology Manager, Poet, History Maniac. Also, a prolific writer on varied topics as diverse as relationships, creativity to technology

To admit the truth, I am not a professional writer. I am just a programmer who became a writer by accident by writing countless technical articles.

And in the course of writing articles, I made mistakes, a lot of them in fact. Some of them made me relearn. Some of them made me cringe and a lot of them opened my eyes and enlarged my myopic viewpoint I had towards writing good articles. However, the common point in all these mistakes were the two golden rules I was able to glean from them.

  • Good technical writing is all about putting old wine in a new bottle with the catch that the old wine should taste better in the new bottle. In simple words, good technical writing does not reinvent or reiterate the concepts again and again that readers know already. Rather it brings out new uses, new applications, and new perspectives from the existing concepts. Therefore, unless you are an inventor or a scientist wanting the change the world, do not reinvent the wheel, rather use the same wheel and invent new uses out of it.

  • Good technical writing is non-technical in nature. Yes, readers have a massive allergy to technical jargon and pretentious words. So if you want them to read and appreciate your technical stuff, write in such a way that an 8-year-old can understand. I know this is easier said than done but there is no other way to put your point across.

Besides the above rules, here are some tips I learned over the years during my journey as a technical writer.

  • Do not start writing anywhere and everywhere. Before you start writing, establish a few places where you can do serious writing without any distractions (your desk in the study, your bedroom, at the garden, etc.). Once you establish the place, make it sacred. Nothing else should be done out there.

  • Prepare a writing chart for the week ahead mentioning the date and times on which you will write. These charts need to track three things 1) Time spent writing.2) Pages completed 3) percentage of planned writing completed. These charts are your motivational and feedback tools in your writing journey.

  • Steal like an artist. Yes, there is no such thing as a new-minted, original idea. And stealing like an artist means reading others’ articles and identifying topics where you can bring your own perspective and treatment based on your experience.

  • The best time to get Ideas is when you are at your groggiest (half-asleep, just waking up, etc.). Studies have proved that our focus broadens when our minds are at our suboptimal level when it creates more connections as it is open and in free-flowing mode.

  • On the other hand, the best time to write is when your creative cells are at their extreme peak and when you are having your best focus (mornings, evenings, or whatever time works for you). Just write in the free flow mode without any interruptions to achieve maximum productivity.

  • Use the ‘combine’ method to find out new ways to connect existing themes. For example, take a piece of paper and write some suggestions in some categories.
    • Programming (e.g. senior programmer, junior programmer, polyglot programmer)
    • Relationships (e.g. casual, long-time, long-distance)
    • Software development techniques (Agile, Kanban, etc.)

Now pick up any two items and write a story. For example, you can write a story about two senior programmers using Agile or you can write about a polyglot junior programmer and so on…...

  • One of the easiest methods to write technical articles is using the Carpenter method that has the following steps.
    • Select the ideas
    • Create the outline of the article into paragraphs (opening. middle and closing)
    • String the ideas within the outline to create the 1st rough draft
    • Tackle one paragraph at a time and polish it further.
    • Read and edit the whole flow and tighten the final piece into a good flowing article

Remember the key message in this style is to let go of perfection. The first draft is imperfect and that is perfectly OK. The final output is your masterpiece, your chef-d’œuvre and only that is important.

  • The problem statement should be clear and should come out the latest by the second paragraph. Yes, many authors neglect to write a clear problem statement leaving the readers scratching their heads figuring out what the writer is trying is tell in the article. The key is to have a clear, concise, and well-articulated problem statement before the solution.

  • Use the ‘inverted pyramid’ concept to structure your solution in such a way that the reader is kept interested. The concept is as follows.
    • Summarize the most important point; the lede.
    • Reveal the direction the article is headed.
    • Flesh out the story with further details added to pique the reader’s curiosity.

  • Do not use jargon. When we say not to use jargon, we are not advocating leaving out necessary technical terms, but we are saying is to ensure that the language is as clear as possible. For example, a hard-core technical term like the “modulator valve control ring.” can also be referred to simply as “tighten the modulator valve control ring securely”, instead of adding complexity like “Apply sufficient torque to the modulator valve control ring to ensure that the control ring assembly is securely attached to the terminal.”

  • Do not use a long word when a short one is available. If writers use pretentious words when other simpler words would convey the same meaning, they risk alienating the reader.
  • Strikeout as many words as possible. The journalist Harold Evans once famously invited readers to consider which words written on a market post signpost can be deleted without altering the meaning. The words were “FRESH FISH SOLD HERE.” Evans told that all the words could be deleted, as fish needs to be “fresh” and “sold”. Therefore, the signpost itself is a waste of money. The idea is to delete and delete and delete ruthlessly until it cannot be deleted further without altering the meaning.

  • Good writing is simple. In fact, the hallmark of good writing is that it can be expressed in a way that reasonably intelligent people can understand. If that is not happening, it just means that the writer has not taken enough pain to present it succinctly. Always boil down a sentence to its simplest form and keep doing it until it cannot be simplified any further.

  • Pacing is the key to reader engagement. When it comes to the flow of your article, what matters most is that the pace you have chosen remains consistent as the plot progresses. A consistent pace (slow, fast, meandering, whatever) keeps the readers engaged and interested until the end.

  • Package your writing in small chunks. The human memory buffers are notoriously short and cannot contain more than 15 words at a time. This puts a constraint on the reader’s understanding and by the time, a reader completes a really long sentence, his buffer gets depleted and he loses track. That is why breaking into small, concise, and meaningful sentences is required to pass the message across succinctly.

  • Speak the language of the audience. For example, a post you write on LinkedIn for senior-level software professionals will read very differently from a post you write on Facebook for the schoolchildren. Not only do these two groups of people have different challenges but their language, their taglines, the lingo they use to speak about their needs also differ considerably. You need to research your audience to know the “kind” of the language they speak and tailor your article accordingly.

  • Be very careful in using tables and charts as sometimes they contain unnecessary information that diverts the reader from your article. Use these artifacts only when they are really required and the reader needs to go through them to understand the gist. Avoid if not required.

  • The closing paragraph should contain both a summary and conclusion, both of which are very important in technical articles. The summary section gives the gist of your article and gives her a ‘flash-card’ type of takeaway that she can register in her mind always. The conclusion on the other hand is the place where the author can conclude the journey of the problem starting from the introduction right until the final resolution. This is also the place where authors can highlight any unresolved issues or even next steps (a sequel to the article maybe?)

  • Acknowledgments and references are often overlooked. There might be the case when you took help from somebody to strengthen your article or maybe you might even have referred his or her book in your research for the article. While a separate section might not be required, but it is always a good practice to be gracious in acknowledging help if taken.

  • Pay attention to food. A proper food balance is important for maintaining healthy nutrition for the mind and body. And recent studies published in Public Health Journal have also proved that it takes just less than 30 minutes to go from a sugar rush to a full-on sugar crash, which means that we get more tired than energized thanks to sugar consumption. The key is moderation. Eating moderately means listening to your body and thereby helping your mind to perform to its full potential. Change yourself for the better.

  • Lastly do not push yourself too hard. Writing need not be as strenuous as running a triathlon. Just write for just 30 minutes to 1 hour and then go about your day. Then on the following day, push yourself a bit harder. Build your writing muscle, one ligament at a time. Not a wasted word. Not a wasted effort. This is the key to be a productive and creative writer.

Related Articles