Writing a Good Technical Article

Introduction

I used to write poems and short stories. When I became a developer, I felt the urge to write as well. Although I haven't been very consistent, I have published some technical articles that I'm pleased with. Every developer should value their ability to write. You can communicate your understanding of a particular technology or issue in writing.

If you want to start writing as a developer today, you don't even need to create a blog from scratch because platforms like Hashnode and Dev.to have already created an excellent environment for you to produce technical content. This article serves as a manual for developers on how to create quality technical content. These are some guidelines that, in my opinion, make you write a good technical article. I sincerely hope you will find my writing enjoyable.😄

PS: I am not an expert and I don't claim to be an expert.

1. Choose a Topic

What gives you the most problems as a developer? What kinds of articles do you want to read yet nobody is writing them? What interests you as a developer? When you want to write an article, you should ask yourself these questions.

Pick a subject based on what interests you and what you want to learn; this will put you in a position to produce the finest article possible. To put it into perspective, your subject should fall somewhere between the three: something you care about, something you know well, and something your audience cares about.

2. Create a catchy title.

The next step is to come up with a title for your subject after you have chosen it. When someone visits your article, the title is the first thing they see.

The headline is what draws the reader's attention on a dashboard with many articles from various authors. The title of an article can influence whether a reader decides to read it or not. If you wish, make it catchy and clickbaity while still being a depiction of the subject you've picked.

3. Do your Research

Even if you are implementing custom React Hooks on a daily basis, writing about them won't be as simple for you. Maybe you are really good so it comes easily, some of us are not. Whether or whether you are an expert in the field, do some research on the subject you have chosen. Simply put, the purpose of the research is to broaden your perspective on your topic.

You can see a different viewpoint on how to do things from your usual method of doing things and possibly learn something you did not know by watching talks on the subject, reading other people's code related to your subject, reading the documentation, and reading other articles. Although it can take longer, three hours of research is enough.

4. Outline Your Article

I usually organize and list the main topics of any technical article before I begin. Create a plan, either on paper or in Notion. You can better understand the entire content as a whole by using an outline and you are well prepared for what you will write and how you will write it.

An outline paints a picture of the primary and supporting concepts of a topic. It can be written in short points or entire sentences, bullet points or Roman numerals—just a simple guide for how to write your article.

5. Be clear and concise

Your paragraphs and sentences should be brief. Long, dense paragraphs can be intimidating. Relay as much as you want while using the least amount of energy. People value their time, therefore you must be concise and to the point.

Avoid waffling; ensure that your writing does not obstruct the message you are trying to express. Adverbs sometimes lead to repetitive words, so try to limit their use in your writing. Tools like Grammarly might assist you in resolving this issue if English is not your first language.

6. Don't write a lot of code without explaining

You write technical content to describe how to use a certain language, library, or framework; for the love of God, do not paste a large portion of code with only a brief description or, worse, with no explanation at all. Imagine you are watching a tutorial and the tutor just keeps pasting the code, that's how annoying your article will sound.

The reader has likely never used the technology before or has little experience with it, so they have chosen your article as a guide to help them learn how to use it. This means that the objective of your article is to teach them how to use it. Divide the code into little blocks and guide the reader with it.

7. Check your grammar

Grammar should be considered while you write your content. Like your dressing on a first date, good grammar in an article communicates a lot. Check your word choice very carefully; affect and effect are two distinct words, and there are other words in the English language that fit this description. Verify that your spellings are accurate.

Additionally, use conjunctions to make your thoughts flow more easily. Make sure that proper nouns and the beginning of phrases are capitalized correctly. Avoid writing numbers, especially big ones, in sentences since it makes them harder to read. The number 249 is preferable than 249 and forty-nine. Use Grammarly to help you correct any mistakes you come across.

8. Use Visuals

Use diagrams and visuals if you can; they speed up learning and are attention-grabbing. Even basic diagrams and graphics will work well. If you are developing a web application, please show us a working demo image along with a well-explained code sample.

The reader will want to read more since they can simply mentally model what to expect. Diagrams.net is one of many free drawing programs available online. Another excellent option is Figma, although you'll need more practice with it.

9. Edit your work. And then edit again.

Take your time to read through and update your article once you are finished. A proofread will be sufficient to catch any errors you may have overlooked. Take a break from the post and proofread with fresh eyes as well; you will read the article in a new state and see things from a different viewpoint, which will help you notice any problems you may have missed.

Editing your work is simply the best approach to ensure that it is of the highest caliber possible when you are putting it out there.

10. If you can, have someone review your draft

I mean literally, get another set of eyes. When you're finished, ask a person you trust who is an expert in your field to review your draft. An additional review is crucial. They could draw your attention to details you missed and provide other approaches.

You get to view the reader's firsthand perspective on your content; who knows, maybe they misunderstood something that, in your opinion, is obvious. It's incredibly important to get feedback, especially from trustworthy sources.

Conclusion

Be confident in your abilities and yourself in addition to the aforementioned advice.
You wouldn't have chosen to write it in the first place if you knew you couldn't do it.
Let's work to produce the highest possible standard of material as tech writers. Treat your writing as a product.

Illustration by Anna Antipina from Ouch!