DEV Community

Elizabeth Schafer
Elizabeth Schafer

Posted on • Updated on

A Starting Point for Writing Technical Blog Posts

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)

Collapse
 
nilomiranda profile image
Danilo Miranda

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

Collapse
 
ssmusoke profile image
Stephen Senkomago Musoke

Excellent post - other ideas

  1. It is your opinion, experience and perspective so does not have to follow what everyone says

  2. The blog post does not have to be very long - can even be a way of keeping notes for your future self

  3. 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

Collapse
 
mdhesari profile image
Mohammad Fazel

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.

Collapse
 
elizabethschafer profile image
Elizabeth Schafer

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.

Collapse
 
nilomiranda profile image
Danilo Miranda

It also helps to fill some knowledge gaps about the topic you didn't even knew you had

Collapse
 
elizabethschafer profile image
Elizabeth Schafer

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.

Collapse
 
nathanenglert profile image
Nathan Englert

This was great, nice work! I've had trouble getting started as well and plan to use this in the future.

Collapse
 
cheahengsoon profile image
Eng Soon Cheah

It's depend which level of audience, for example newbie.

Collapse
 
erclairebaer profile image
Claire McCrea

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.

Collapse
 
elizabethschafer profile image
Elizabeth Schafer

That's a really good point. Listing prerequisites before the post would be a great way to point beginners in the right direction.

Collapse
 
fannyvieira profile image
Fanny

<3

Collapse
 
adegbengaagoro profile image
Agoro, Adegbenga. B

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

Collapse
 
niro profile image
Arnau

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.

Collapse
 
elizabethschafer profile image
Elizabeth Schafer
Collapse
 
pavlosisaris profile image
Paul Isaris

Nice guide, thanks for sharing!