I've accumulated a lot of useful info as a front end developer over the years, and want to be able to share that with others. Unfortunately, teaching doesn't come naturally to me. I feel like I need to simultaneously know everything and teach everything all at once, which of course is impossible. I also have a hard time narrowing down what the most important concepts are because everything seems equally important to me.
When I decided to try writing a technical blog post, I searched around to see if there were any guidelines or best practices I might be able to follow. That's when I came across howtoegghead.com, which is a guide for egghead.io instructors on how to create lessons. I found it really helpful, and highly recommend reading through it if you're looking for guidance.
Here's a summary of the points I found most useful (adapted for blog posts), plus some of my own thoughts. Full disclosure: this is all new to me, and mostly just notes to myself as a way to encourage myself to write more.
Decide what to write about
Some ideas for topics:
- something you're passionate about
- something you've learned recently, or are in the process of learning
- something you've figured out recently (e.g., a confusing bug or unexpected edge case)
- something that seems super simple to you, but might be a big help to anyone less experienced
Make sure to narrow this down to something very specific. It should be something you can talk about in just a few minutes. For example, my thought process might be something like this:
- I'm passionate about accessibility, so I should write about that! - This is way too broad. I wouldn't even know where to start.
- Being able to use a keyboard to navigate a website is important. - A little better, but still too much to cover.
- The first thing I notice with keyboard navigation is how important it is for focus states to be visible and easy to spot. - Much better. This is finally something I can start wrapping my head around.
- I'll talk specifically about button focus states. Perfect! This sounds pretty simple on the surface, but there's a lot I can talk about.
What I love about this is that I could potentially write a series of short, related posts that each go into detail about one specific thing. It gives me permission to leave out extra details that I feel like I should mention, but don't necessarily contribute to the current topic.
It's totally fine if you want to write about something that other people have already written about. By writing in your own words, you're giving people another viewpoint that might make things click. It's also a great way for you to reinforce what you've learned, and for your future self to reference.
Some of my favorite blog posts are ones that cover the absolute basics of HTML and CSS. These are things that have been covered many times already, but I always learn something new.
It doesn't matter if you're a beginner. If you're a beginner, you might work through things in a way that makes sense to other beginners. Someone more experienced might include a code snippet without explicitly stating which file that code is supposed to go in. Or they might include something to run from the command line without explaining that you first need to be in the right working directory. Those are the types of things I get stuck on when I'm learning something new, and they're usually hard to figure out when you don't know how things work yet.
Be clear and to the point
Assume your readers already have the required background knowledge. If there's anything they don't know, they can look it up on their own.
Don't include an intro, outro, or stage-setting. Think about when you search for a recipe and have to read someone's life story before you find the ingredient list. We want to keep it simple, so include only the content people are looking for.
Show your work
Include a series of editable code examples. It's one thing to read about something, and another to see it in action. Instead of describing everything in words, use code examples to prove your point. Here's an example of what I mean:
By including a series of examples, readers can see each step of the process and how it affects the result. And since these can be edited, readers have the option of playing around with the code to get a better understanding of how things work.
Now you're ready to write!
I put this together because I was having a hard time getting started without a list of guidelines to follow. Now that I have a starting point, I'm hoping it will help make the writing process easier for me in the future.
Are there any resources you use to figure out what to write about or how to structure your posts? Or do you have a specific process you like to follow that works for you? I'd love to learn more about how others are doing this!
One thing I found after writing most of this was Ali Spittel's blog post workflow which goes more in-depth - would've been helpful if I'd noticed that first! 😉
Top comments (15)
I already have a few posts written here, but I was just thinking about searching for information on how to write technical blog posts... Then I opened dev.to and your post was in my feed
That's why I don't believe in coincidence
Excellent post - other ideas
It is your opinion, experience and perspective so does not have to follow what everyone says
The blog post does not have to be very long - can even be a way of keeping notes for your future self
Even if many people do not read for a while, keep writing you will get to a tipping point
I use writing as a way of giving back to the community for the time they have spent helping me
Researching a lot about the subject you are going to write could help you to discover ideas and also it leads you to write more unique and adequate content.
Definitely! That reminds me, I also like to include a list of related resources that I found helpful at the end of the post. That's another way for me to feel less pressure about covering every single thing, because readers can follow those links if they're interested in learning more.
It also helps to fill some knowledge gaps about the topic you didn't even knew you had
Yup! The same thing happens when I get stuck on some code and need to ask for help. I'll start writing up a description of the problem, and in the middle of that, I'll notice things I had missed before.
This was great, nice work! I've had trouble getting started as well and plan to use this in the future.
It's depend which level of audience, for example newbie.
Agreed. If you're going to say "assume your readers already have the required background knowledge," you need to start off by saying what knowledge you're assuming they know.
That's a really good point. Listing prerequisites before the post would be a great way to point beginners in the right direction.
<3
This is really great. Been struggling with this for a while now and it has proven to be a great guide.
Thanks again for sharing
Great article! I was wondering how did you make that profile avatar. I want to make on for myself but I don't know how.
getavataaars.com/
Nice guide, thanks for sharing!