DEV Community

Arkodyuti Saha
Arkodyuti Saha

Posted on


Writing a technical blog 101

Let’s do a quick quiz!

1. Do you remember the Schrödinger wave equation?
2. Do you remember the name of the Disney princess with the longest hair in town?
3. Do you remember the scientific name of the frog?
4. Do you remember the story of the Princess and the Frog?

Yes, while we read of Rapunzel and the frog as kids in kindergarten, we don’t even remember stuff we studied only a couple of years ago, stuff that was essential for us to pass exams, get into big institutes and make our parents proud!

This, my friend is the Power of Storytelling.

When you’re writing any blog whether technical or non-technical the motive is to ultimately tell a story. There are a few tips and tricks to writing amazing technical blogposts.

Alt text of image

🏷️ Intro – Be a Storyteller
Surface device products to your favorite thriller on Netflix – what kept you hooked in was an appealing story i.e. a short video of say 1min or a little more. Similarly, when you are writing a blog you need to have a story outline to tell which will keep your users scroll till the end. The intro section of the blog needs to be short and crisp and covering broadly three things –

✔️ Why are you writing this article – the background story behind it
✔️ What you are going to cover in this blog
✔️ Who is going to read this blog?

Just a note–typically a technical blogpost could either be a tutorial that people can follow step by step, or it should at least teach something interesting

🏷️ Base – this is the layer with a lot of substance in it
Contextual Relevance - utilize this section of your blog to go in-depth about the topic you’re trying to focus on in your article. Have a structure in this section from stepwise procedures, relevant code snippets, documentation, architecture/flow diagrams and hyperlinks to other relevant articles (if any).

We need to be mindful of three major pointers in this section –

✅ Headline
✅ Images/Videos
✅ Formatting

A few tools/features which can help you shape your blogs –

☑️ Markdown – If you’re writing on make sure you are familiar with the Markdown syntax
☑️Snagit – can help you capture screenshots for your blog
☑️ Use Cloudinary to add and manage images/videos to your blog
☑️ Color contrast analyzer tool - helps with the text to background-color
☑️ Words choice e.g. Click instead of mouse
☑️ Put alt-text on images
☑️ Hyperlink phrases or words that describe the site instead of saying "here"

Note: If you are creating a tutorial/demo video for your article – it’s always great to upload it on YouTube/Twitch Channel and link it to your blog.

Alt text of image

🏷️ Conclusion – Publicize your piece of content
This is the last lap of the race – which is going to take quite some effort. A few things you can do to drive users to your blog is –

✔️ Packaging your entire content – create a header image for your blog, add subtitles
✔️ Post it in relevant publications. For example, if you’re writing a blog post on Using Cognitive Services of Microsoft Azure – your go-to place should be Azure Publication on or Medium.
✔️ Social Hype – Tweet/Share on relevant Facebook Groups/Newsletters (if possible)

The core intention of writing technical blogs is to “help developers” – like any technology advocate to help the broader community. Write what the community wants, address the problems that the community wants, keep shaping products the way the community wants. That’s how a healthy DevRel 🥑 is like. Check out some of the awesome blogs under the Microsoft Azure publication on

Alt text of image

Top comments (6)

michaeltharrington profile image
Michael Tharrington

This was a really cool read, thanks for sharing!

It makes me think of the writerly advice "show, don't tell" which may also be helpful advice here. "Show, don't tell" is more applicable to creative writing, but as you're talking about taking a storytelling approach to technical writing, I think it fits alright!

sanjeevk profile image
Sanjeev Kumar

Nice one. I have little bit experience in technical writing, but thanks for you article. Previously i write up one blog on What Are The Principles of Good Writing please share your thought on this.

tersarset profile image
Tersarset • Edited

Nowadays writing is such an amazing work to earn money and show skills. If you are good in writing that will be helpful for you, like you can check here you will get info about how to make money by as a freelance writer. I hope you will use this useful information, normally I share or gain more knowledge in my free time.

steelwolf180 profile image
Max Ong Zong Bao

Awesome article that I wish I had learnt about when i was starting on my blog.

arkodyutisaha profile image
Arkodyuti Saha

Thanks, Max :)