21 Tips to Write Good Technical Articles
By: Mythili The Dreamer
Tags: Startup, Technology, Software Engineering, Programming, Writing

The Tips

Don’t 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 datess and times at which you’ll write

These charts need to track a minimum of three things: (1) time spent writing, (2) pages completed, and (3) the percentage of planned writing completed. These charts provide the motivation and feedback you need for your writing journey.

Steal like an artist

Yes, there’s 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 unique experience.

The best time to get ideas is when you’re at your groggiest (half asleep, just waking up, etc.)

Studies have proved that our focus broadens when our minds are at a suboptimal level, allowing us to create more connections, as we’re open and in a 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’re having your best focus (mornings, evenings, or whatever time works for you)

Just write in the free-flow mode without any interruptions in order to achieve maximum productivity.

Combine ideas to find 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 the story about two senior programmers using Agile, or you can write about a polyglot junior programmer.

One of the easiest methods to write technical articles is by using the Carpenter method

Select the ideas. Breakdown/outline your intended article into paragraphs (opening. middle and closing). String the ideas within the outline to create the first 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 nicely flowing article.

Remember the key message in this style is to let go of perfection. The first draft is imperfect, and that’s 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 be delivered by the second paragraph — at the latest

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 them 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 stays 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.

Don’t use jargon

When I say not to use jargon, I’m not advocating leaving out necessary technical terms, but I’m saying it is to ensure the language is as clear as possible.

For example, a hardcore technical term like the modulator valve control ring can be referred to simply: “Tighten the modulator valve control ring securely.” This is preferable to 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.”

Don’t 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.

Strike out as many words as possible

The journalist Harold Evans once famously invited readers to consider which words written on a market signpost can be deleted without altering the meaning. The words were “FRESH FISH SOLD HERE.”

Evans said all of the words can be deleted, as fish needs to be fresh and sold. So the signpost itself is a waste of money. The idea is to delete and delete and delete ruthlessly until nothing can be deleted any further without altering the meaning.

Good writing is simple

In fact, the hallmark of good writing is it can be expressed in a way that reasonably intelligent people can understand. If that’s not happening, it just means the writer hasn’t taken enough pain to present it succinctly. Always boil down a sentence to its simplest form, and keep doing it until it can’t 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’ve chosen remains consistent as the article progresses. A consistent pace (slow, fast, meandering, etc.) keeps the reader engaged and interested until the end.

Package your writing in small chunks

Human-memory buffers are notoriously short and can’t 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, their buffer gets depleted and they lose track. That’s why breaking your copy 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 school children. Not only do these two groups of people have different challenges, but their language, their taglines, and the lingo they use to speak about their needs also differ considerably.

You need to research your audience to know the kind of language they speak and tailor your article accordingly.

Be very careful when using tables and charts, as sometimes they contain unnecessary information that diverts the reader from your article

Use these artifacts only when they’re 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 a conclusion, both of which are very important in technical articles

The summary section gives the gist of your article and gives your reader a flash-card type of takeaway.

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

You may have gotten help from somebody to strengthen your article or maybe you referred to a book in your research for the article. While a separate section might not be required, it’s 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 the Public Health Journal have also proved it takes less than 30 minutes to go from a sugar rush to a full-on sugar crash, which means 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. Charge yourself into a better writer.

Lastly, don’t push yourself too hard

Writing needn’t be as strenuous as running a triathlon. Just write for 30 minutes to one 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 being a productive and creative writer.