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.

🏷️ 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 dev.to 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.

🏷️ 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 dev.to 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 dev.to