What are some best practice while writing a technical article - Issue #30

Nov 25, 2022

What are some best practice while writing a technical article?

Writing technical articles for over 2.5 years has led me to know some best practices while writing articles. This practice is quite simple to implement in your writing. It will massively improve your article.

So, let's get started.

A Good Structure

Divide the complete article into different headings and sub-heading for better understanding. I see a lot of articles without headings and well structure. It is quite hard for the reader to find a useful section.

Adding Image

Try to add relevant images and screenshots to the article. Add proper captions to these images for accessibility purposes. Adding images will also increase the scrollable area of your article.

Use code blocks effectively

As a technical writer, you will need to add code blocks to your article. Always mention the programming language to code blocks for proper syntax highlighting. In markdown, you can add this after adding ``` then the name of the programming language. For instance, ```javascript for a code block of JavaScript.

Meaningful title and cover image

The title and cover image will attract an audience to your blog. So, use them wisely. You can frame your article that creates curiosity. Instead of "Building an application", you can use "How I build an application". For the tooling article, you can use the number in your title. For instance, 10 GumRoad products for Developers and 40+ Useful Resources for Mastering the Web.

As for the cover image, you should include both an image and the second title of your article. You can use canva for creating a template for your article. Be consistent in the design of your thumbnail. Pick a template and just add an image and title for each article. Don't try to create completely different thumbnails for different articles.

Use Grammar tool

Use tools like Grammarly to lower the grammar error in the article. You can also use the Hemingway editor to crop lengthy sentences.

Read your article completely from beginning to top once after completing the draft. It will help you in finding errors in the structure and flow of the article.

Conclusion

I think this is enough for this part. I might create another part of it to discuss a further little bit of more advanced formatting. Till then, try to implement the above tips in your writing.

I hope this, week's issue has provided you with some awesome content. Thanks for reading the newsletter.