Updated date:

21 Tips to Write a Good Technical Article

Author:

Ravi loves writing within the cusp of relationships, technology, and creativity where boundaries are blurred and possibilities are immense

A good technical article must be non-technical, useful, and simple in that order.

A good technical article must be non-technical, useful, and simple in that order.

The Two Golden Rules of Technical Writing

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 while 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 the myopic viewpoint I had towards writing good articles.

However, the common point in all these mistakes was 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.

1.Establish a Writing Place

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, in the garden, etc.). Once you establish the place, make it sacred. Nothing else should be done out there.

2.Prepare a Writing Chart

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

  • Time spent writing.
  • Pages completed
  • Percentage of planned writing completed.

These charts are your motivational and feedback tools in your writing journey.

3.Steal Like an Artist

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.

4.Think While Half-Awake

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.

5.Write at Your Best Time

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.

6.Use the “Combine” Method to Connect Themes

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…...

Use the “Carpenter” Method to Create Your Article

Use the “Carpenter” Method to Create Your Article

7.Use the “Carpenter” Method to Create Your Article

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.

8.The Problem Statement Should Be Clear

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 Article

Use the ‘Inverted Pyramid’ Concept to Structure Your Article

9.Use the ‘Inverted Pyramid’ Concept to Structure Your Article

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

Do Not Use Jargon

10.Do Not Use Jargon

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.”

11.Use Short Words

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.

12.Strike Out 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.

13.Good Writing Is Simple

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.

14.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.

15.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 are required to pass the message across succinctly.

16.Speak the Language of the Audience

Writing style differs from medium to medium. For example, 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.

17.Use Tables and Charts Sparingly

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.

18.The Closing Paragraph Is Important

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 Important

Acknowledgments and References Are Important

19.Acknowledgments and References Are Important

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.

20.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.

21.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.

As Matt Fitzgerald has rightly said.

Build step by step. Push yourself but not too hard. Learn. Keep it fun.

— Matt Fitzgerald

This content is accurate and true to the best of the author’s knowledge and is not meant to substitute for formal and individualized advice from a qualified professional.

© 2021 Ravi Rajan

Comments

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Audrey for your comments

Audrey Hunt from Idyllwild Ca. on June 05, 2021:

Excellent writing tips.A good reminder and thank you.

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Thelma for your comments

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Bill for your comments

Thelma Alberts from Germany on June 05, 2021:

Great tips. A very good information. Thank you for sharing.

Bill Holland from Olympia, WA on June 05, 2021:

All great tips, my friend! A very nice resource for writers.

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Rawan for your comments

Rawan Osama from Egypt on June 05, 2021:

It is very usefel topic

Thank you for sharing it

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Rosina for your kind comments

Rosina S Khan on June 05, 2021:

I agree with you that technical articles should be written in a step by step easy-to-understand way. While writing these articles, it's really good to remember and apply the points you make in your article. Thank you, Ravi, for such a helpful article.

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Misbah for your kind comments

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Chitrangada for your kind comments

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Devika

Misbah Sheikh from The World of Poets on June 05, 2021:

Ravi, you've given some excellent advice. Exceptionally good ideas. The information in this article is quite beneficial. May God continue to bless you.

Chitrangada Sharan from New Delhi, India on June 05, 2021:

Excellent points about writing a good technical article. These tips apply to the craft of writing, as well.

Very well made points, and well written. Thank you for sharing.

Devika Primić from Dubrovnik, Croatia on June 05, 2021:

Informative and useful tips.

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks, Miebakagh for your kind comments.

Miebakagh Fiberesima from Port Harcourt, Rivers State, NIGERIA. on June 05, 2021:

Ravi, thanks for sharing.

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks Umesh

Ravi Rajan (author) from Mumbai on June 05, 2021:

Thanks, Liz for your comments

Liz Westwood from UK on June 05, 2021:

This is a well-rounded and extremely helpful article. A lot of your principles have a wider application to other genres of writing. I especially appreciated your multi-faceted approach. You come at the subject from a wide variety of different angles.

Umesh Chandra Bhatt from Kharghar, Navi Mumbai, India on June 05, 2021:

Very nice. Very useful.

Related Articles