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)
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
🤔 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. 🤓
Nice, can't wait
Found some really good articles on your blog, I will go consume those while I await 🙂
Just in case the tag didn't work, here's the blog post response to this.
@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.
Here are some tips to help you write a great technical article:
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 😅
Also it's much less stress than trying to make everything right so that you can finally press publish.
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.
Thanks Abbey for sharing, inspiring post.
Thank you for the tips Abbey! ☺️
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
Guide
Reference
Thanks, it is now clear for me
Some comments have been hidden by the post's author - find out more