DEV Community

Cover image for The Ultimate Guide to Writing Technical Blog Posts

The Ultimate Guide to Writing Technical Blog Posts

Rizèl Scarlett on June 06, 2023

Table of Contents Really long introduction about how I started writing tech blog posts Address your fears Keep a list of things you’...
Collapse
 
ajcwebdev profile image
ajcwebdev

Amazing job Rizel, this is epic! Since it's a pretty lengthy article an outline will probably help with navigating around the different sections, feel free to copy paste this if you want.

Outline

## Outline

- [Really long introduction about how I started writing tech blog posts](#really-long-introduction-about-how-i-started-writing-tech-blog-posts)
  - [Address your fears](#address-your-fears)
  - [Keep a list of things you’ve learned](#keep-a-list-of-things-youve-learned)
  - [Choose the topic you feel most excited about](#choose-the-topic-you-feel-most-excited-about)
  - [Read other blog posts for inspiration](#read-other-blog-posts-for-inspiration)
  - [Determine your audience](#determine-your-audience)
  - [Build an outline](#build-an-outline)
  - [Take a shower](#take-a-shower)
  - [Enter a flow state for writing](#enter-a-flow-state-for-writing)
  - [Struggle with writing? Record your voice](#struggle-with-writing-record-your-voice)
  - [Read it aloud (or use a Text-to-Speech reader)](#read-it-aloud-or-use-a-texttospeech-reader)
  - [Use a digital writing assistant](#use-a-digital-writing-assistant)
  - [Share your draft with stakeholders to gather feedback](#share-your-draft-with-stakeholders-to-gather-feedback)
  - [Add a cover image](#add-a-cover-image)
  - [Publish](#publish)
  - [Share it on social media](#share-it-on-social-media)
- [Additional Resource](#additional-resource)
- [Conclusion](#conclusion)
- [Call to action](#call-to-action)
Enter fullscreen mode Exit fullscreen mode

You can technically link to these headers as well in the outline section, but you can't double nest bullet points so I left them out:

- [Outline for “how-to” blog posts](#outline-for-howto-blog-posts)
- [Outline for explainer blog posts](#outline-for-explainer-blog-posts)
- [Outline for thought leadership/opinion blog posts](#outline-for-thought-leadershipopinion-blog-posts)
- [Outline for listicle blog posts](#outline-for-listicle-blog-posts)
Enter fullscreen mode Exit fullscreen mode
Collapse
 
blackgirlbytes profile image
Rizèl Scarlett • Edited

Thank you, this is what I have in Hashnode. See here: blackgirlbytes.dev/the-ultimate-gu...

It looks way easier to navigate on Hashnode, but I didn't know you could maually add a table of contents with markdown in DEV. To be honest, I always struggle with any kind of formatting with DEV. Will copy and paste this.

Thank you!

Collapse
 
gabrielfallen profile image
Alexander Chichigin

Great post and lot of good advise! I've bookmarked it and plan on reading the whole series from the start now. Thanks!

Though you don't mention another great feature of outlines: they are easy to discuss with other people and adjust. Shall we provide an example? 😉

You start every outline with a "hook" but you don't explain what you mean by it and what it can look like? In particular, how is it different from a "brief overview of the topic and why care"?

Also I might change the order of subsections in an explainer post from

1. Key Concept 1
    - Definition/explanation
    - Examples 
    - Importance or relevance
Enter fullscreen mode Exit fullscreen mode

to

1. Key Concept 1
    - Examples
    - Definition/explanation
    - Importance or relevance
Enter fullscreen mode Exit fullscreen mode

I think (mostly following advice from much more experienced writers) examples serve as a better intro to a concept for majority of readers, and definitions become easier to understand when you can connect them to an instance of a concept that's still fresh in your mind.

So what do you think? What's your reasoning for these questions? 😃

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett • Edited

Hey there!! Thanks for the comment..and excited that you will read the rest of my series.

I don't full understand this question. Do you mind elaborating --

Though you don't mention another great feature of outlines: they are easy to discuss with other people and adjust. Shall we provide an example? 😉

You brought up fair points! My reasoning for not explaining what a hook is..is that I don't believe in using a blog post to explain every single detail. That would be a whole novel 😆. However, this may be a good opportunity for me to branch off and do a follow up post on how to write a good hook or explain what a hook is.

I think both options for outlines work. If the person wants to do an example first, they can! I like to give an explanation or definition of what it is, so that you can have context, then see an example of it in action. I don't want to show my reader an example of something, but they have no clue what it is. Then, I do an explanation of why it matters. This format works really well for me, and has enabled me to have very high engagement on many of my blog posts. To me, that shows that people understand the way I've explained the content and take a liking for my format.

In some of my blog posts, I switch the order. I'm not a stickler for how a blog post NEEDS to be written and I consider the outlines I created to be guides to help you get started. However, I think every writer should have their own choice and use the format that works best for them. Every writer has their own style and voice.

Hope that answers the question!

Collapse
 
gabrielfallen profile image
Alexander Chichigin

This perfectly answers the questions, thanks a lot!

I don't full understand this question. Do you mind elaborating

That wasn't a question, that meant to be an intro (a hook???) into the actual questions coming next. Unsuccessful evidently. 😅

Looking forward for a post on hooks!

Collapse
 
freecoderx profile image
FreeCoderX

Very much for your wonderful sharing, received a lot of dry goods

Collapse
 
bcouetil profile image
Benoit COUETIL 💫

"Ultimate" is too much when the author is that young 🤔

I hope there are at least some good advice in it, and that junior developers won't be misled too much by believing blindly the title🤞

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett • Edited

Well thank you for saying I was super young. Not sure how young you think I am, but black dont crack 😂. I know my writing skills are very strong, which is why I can confidently call it the ULTIMATE guide to writing tech blog posts. My tech blogging has accelerated my career, and I just wanted to share knowledge and wealth with technologists of all levels. It sounds like you only read the title and not the actual blog. I’d encourage you to read it if you get a chance. I put my heart and soul into it.

Collapse
 
samuelodan profile image
Samuel O'Daniels

Hi, I’m not done reading your post, but I’ve gotten a lot of good advice already.
Thanks for taking the time to write it.

Thread Thread
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you!! That makes me feel great.

Collapse
 
onlinemsr profile image
Raja MSR

While someone may have already written about a similar topic, they won’t explain it the same way you will. And the way you explain and describe information will reach a particular audience that learns and consumes information the same way you do.

That's 100% true.

Collapse
 
jwilliams profile image
Jessica williams

Amazing Rizel. as a content writer I always wanted to write something like this and after reading this i got many ideas which I can use in my blog as well.

Keep writing and keep rising.

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

I’d love to see your version or advice for writing a blog post! Thank you so much!

Collapse
 
jwilliams profile image
Jessica williams

Will write something soon Rizel.

Collapse
 
thesonicstar profile image
thesonicstar

Thank you very much for this!! - I have recently started blogging my work and sometimes run out of ideas or how to construct them. So these tips will help me feel better about my posts! - Feel free to check them out and pass back any feedback you have! :)

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you so much! Also I checked out your blog posts. Love them. Easy to comprehend but very informative. My only advice that could possibly take them to the next level is adding some more imagery inside the posts. Besides that, looks amazing. Keep writing!

Collapse
 
lymah profile image
Lymah

This is epic!

Collapse
 
faraib profile image
Farai Bvuma

Great post! I hadn't thought of the possibility of using AI to create a cover image.

Collapse
 
juanfrank77 profile image
Juan F Gonzalez

Very comprehensive post. 👏

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you!

Collapse
 
kurealnum profile image
Oscar

10/10 advice! I was going to start utilizing an outline/plan when I write, and I think I just found it!

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you!

Collapse
 
pachicodes profile image
Pachi 🥑

Awesome Article Riz!!!

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thanks Pachi!!!

Collapse
 
hassansuhaib profile image
Hassan Suhaib

This is amazing advice. Thanks for sharing your templates. I have a question: Should I write my technical blog posts on medium or dev.to?

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Depends on where your audience is. In my opinion, Medium is more geared towards business and Dev.to or Hashnode is geared towards developers. I cross post on both Hashnode and DEV. You can cross-post if you want as an experiment to see where you get the most engagement.

Collapse
 
hassansuhaib profile image
Hassan Suhaib

Oh ok. Thanks!

Collapse
 
veemish profile image
VERONICA MICHAEL

Thank you so much @blackgirlbytes this came the very perfect time for me. It’s been a struggle but reading it here makes it seem all Soo possible

Collapse
 
inaju profile image
mitchel inaju

Thank you so much for writing this, this was really helpful

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you!

Collapse
 
sidipak profile image
Saiful Islam

Thanks. Comprehensive. "Read it aloud (or use a Text-to-Speech reader)" is a new idea for me :)

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Yeah I cant take credit for it. I’m not sure who told me about it, but ever since, it’s been a game-changer.

Collapse
 
_wcyd profile image
Aditya

Have you monetized your blog ? If yes then can you share how to earn money by technical writing.

Collapse
 
melissakaulfuss profile image
Mel Kaulfuss

THANK YOU! This is amazing!

Collapse
 
blackgirlbytes profile image
Rizèl Scarlett

Thank you!