DEV Community

Cover image for Writing a Technical Blog
Abbey Perini
Abbey Perini

Posted on • Updated on

Writing a Technical Blog

I wrote about how I structure my writing in general last November, as part of the 14,584 words I wrote for Virtual Coffee's blogging monthly challenge. This will be my 14th blog this November, and I found myself reflecting on how I get my ideas and turn them into published technical blogs.

Ideas

Anytime you solve a problem or learn something new is great time for a blog. Write a blog when you:

  • Explain something to a coworker
  • Finish a big feature at work
  • Dive down a research rabbit hole
  • Want to research something so you understand it a little better
  • Build something just for fun
  • Want to take detailed notes on something you just figured out

Once you have your idea, decide if you're making a guide or reference.

Guide

A guide takes the reader through building or doing something step by step. If you want to make a guide, there a few questions to ask yourself:

  • What skill level am I writing for?
  • What knowledge does the reader need to understand this?

You want to open the blog by declaring any prerequisites. This prevents you from having to explain every single concept you use. For example, if you're building something in React, say "This blog assumes you are familiar with React."

Next, ask yourself, what is square 1? What is a completely blank slate? Start the instructions there.

Blocks of code visually break up text, which is good for moving the eye along. However, don't expect your code to explain itself. It's like explaining a problem and its solution to a coworker - you need to give context. This includes names of files, if your code spans multiple files.

Reference

A reference article explains or teaches a concept. Rather than step by step instructions, you want to focus on summarizing an idea. I start by making an outline with headings.

As I start to describe a concept, I usually realize there's more I have to explain. That means adding headings to my outline or even breaking it out into a whole new blog.

The opposite of a guide, reference blogs quickly get dense, so it's important to break up the text. I use headings and memes.

Editing

Leave it sitting for a day or two and come back and read the whole thing, out loud. You'll be surprised what typos you find. If you can get someone else to read it for you and give feedback, even better.

In rereading, I often find I've used a word a lot and have to reword sentences. "Often" has been one of them recently.

I'll fine-tune explanations and be more explicit about how concepts relate to each other. With guides, I'll follow the steps myself.

Conclusion

Anytime you want to understand a concept a little better, explain it to someone else. Technical blogs are a great way to help yourself and others learn at the same time.

Top comments (14)

Collapse
 
teejay128 profile image
Joseph Taiwo

Just started writing recently, and I can relate to the one were you leave your article for a while and come back later, it usually feels to me like I am reading and essay I wrote when I was 10 ๐Ÿ˜…

I have had problems writing references though, I find it easier to write guides and documentation, also wondering if you could whip up something to help with writing references. Thank you

Collapse
 
abbeyperini profile image
Abbey Perini

๐Ÿค” I'll have to think on that one. I learned by writing research papers and having to cite my sources.

I would love to share the note card method my middle school science teacher taught me, but I'd have to apply it to online resources and give a digital format. ๐Ÿค“

Collapse
 
teejay128 profile image
Joseph Taiwo

Nice, can't wait

Found some really good articles on your blog, I will go consume those while I await ๐Ÿ™‚

Thread Thread
 
abbeyperini profile image
Abbey Perini

Just in case the tag didn't work, here's the blog post response to this.

Collapse
 
vijaykhatri96 profile image
Vijay Singh Khatri

@abbey This is an awesome writeup; even after contributing so long feels like something I missed that I am used to.

Thanks for sharing your quick insights about how one should start their content writing journey especially in Tech Domain.

Collapse
 
vijaykhatri96 profile image
Info Comment hidden by post author - thread only accessible via permalink
Vijay Singh Khatri

Here are some tips to help you write a great technical article:

  1. Start by choosing a specific topic that you have expertise in that is relevant to your audience. This will help you focus your article and make it more useful and interesting to your readers.
  2. Research your topic thoroughly to ensure that you have a deep understanding of the subject. This will help you provide accurate and up-to-date information in your article.
  3. Use clear and concise language to explain technical concepts in a way that is easy to understand. Avoid using jargon or complex terminology that may be confusing to your readers.
  4. Organize your article in a logical and easy-to-follow structure. This will help your readers understand and retain the information you are presenting.
  5. Use examples and visuals to help illustrate your points and make your article more engaging. This can include diagrams, charts, graphs, and other visual aids.
  6. Proofread your article carefully to ensure it is free of errors and mistakes. This will help you avoid any confusion or misunderstandings that may arise from incorrect information.
Collapse
 
joshuaslate profile image
Joshua Slate

Thank you, Abbey. I just decided to start up a blog again after many years, and these are some great tips. I particularly like the one about letting things sit for a day or two before hitting the publish button. It's bad for instant gratification, but great for finding mistakes and clearer ways of wording things. It's certainly been interesting coming back to longer-form writing after not having to write much more than an email-length piece since college ๐Ÿ˜…

Collapse
 
jmfayard profile image
Jean-Michel ๐Ÿ•ต๐Ÿปโ€โ™‚๏ธ Fayard

Also it's much less stress than trying to make everything right so that you can finally press publish.

Collapse
 
nneka_onochie profile image
Nneka Onochie

This is a very insightful piece because I want to start blogging.
I learned some vital skills that will guide me through the starting process. Thank you for letting this out.

Collapse
 
borzoomv profile image
Borzoo Moazami

Thanks Abbey for sharing, inspiring post.

Collapse
 
360macky profile image
Marcelo Arias

Thank you for the tips Abbey! โ˜บ๏ธ

Collapse
 
le_woudar profile image
Kevin Tewouda

Hi Abbey, nice article. However I don't understand the difference between a guide and a reference. Could you give me examples in both categories so I can see the difference? Thanks

Collapse
 
abbeyperini profile image
Abbey Perini
Collapse
 
le_woudar profile image
Kevin Tewouda

Thanks, it is now clear for me

Some comments have been hidden by the post's author - find out more