The Ultimate Guide to Writing Technical Blog Posts

Table of Contents

• Really long introduction about how I started writing tech blog posts
  • Address your fears
  • Keep a list of things you’ve learned
  • Choose the topic you feel most excited about
  • Read other blog posts for inspiration
  • Determine your audience
  • Build an outline
  • Take a shower
  • Enter a flow state for writing
  • Struggle with writing? Record your voice
  • Read it aloud (or use a Text-to-Speech reader)
  • Use a digital writing assistant
  • Share your draft with stakeholders to gather feedback
  • Add a cover image
  • Publish
  • Share it on social media
• Additional Resource
• Conclusion
• Call to action

Really long introduction about how I started writing tech blog posts

Technical skill and content creation are equally important for your software development or (software development adjacent) career. Technical skills such as coding help you to perform the job at a base level, but content creation can solidify you as a leader in the industry. I acknowledge that not everyone has the privilege of creating content alongside completing their daily job duties and personal responsibilities, but it is a worthy investment. Creating technical content can make it easier to land jobs, get promoted, and influence the direction of our industry because it enables hiring managers and other tech leaders to take a peek into your brain and your thought process. More importantly, it helps you absorb and solidify concepts that you’ve learned. You can be the smartest, most skilled software developer in the world, but if no one knows who you are, then your opportunities may be limited. Content creation helps you advocate for yourself. It might seem cringe, but you can put yourself out there in a non-cringey authentic way. Folks like Kelsey Hightower established and advanced their careers by sharing their thoughts in an authentic and thoughtful way.

My favorite form of technical content creation is blogging. Thanks to my mom, I developed a passion for reading and writing at an early age, so writing has always been my preferred method of self-expression. I had an endless supply of picture books, cassette-tape audio books, novels, poetry, and half-filled notebooks documenting my childhood experiences. When there was no heat in my house, my mom would bring my siblings and me to the library, so the library became my second home. Disclaimer: I’m not a perfect writer; it’s just something I enjoy doing.

Unfortunately, I abandoned writing in early adulthood because I learned that it’s hard to make money as a writer, and I had one goal in mind: make LOADS of money. I grew up poor, and I was determined to improve my quality of life, so I focused all my energy on a career that makes money: software development.

Years later, I started my third full-time software development job, and my manager Andy Cunningham encouraged me to write what I learned on the job. As part of my sprint, I’d fix a bug or implement a new feature, and then I would write about it. One of my first technical blog posts was about how I used GitHub Actions to sync our repository with our AWS S3 Buckets. Months later, I landed my current role as a Developer Advocate, and part of my role is to blog.

While I was excited to combine my childhood skill (writing) with the skill I learned in adulthood (coding), I was also intimidated. Writing about technology didn’t seem as easy as writing a poem or an essay. With poetry, I had all creative authority, and with essays, teachers gave us guidelines. But, what was a technical blog post supposed to look like? I worried and struggled with the following concepts:

• Will people read it or even care to read it?
• Will people think I’m wrong or stupid?
• Do I have anything valuable to say?
• Is my blog post too short?
• Is my blog post too long and overwhelming?
• I want to tell the audience everything, but when should I stop the blog post?

I didn’t have any structure or strategy for writing my blog posts. After a year of writing technical blog posts and learning from great content creators like Kurt Kemple, I’ve developed a strategy that I’m comfortable with. In this blog post, I’ll share my strategy in hopes of empowering you.

Address your fears

A common reason that technologists don’t write is because they’re scared.

If you’re scared that you don’t have anything new or different to write about…
Remind yourself that you don’t have to write about anything revolutionary or inventive, write what you know. 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.

If you’re scared that your writing skills aren’t up to par…
Remind yourself that this is your platform to practice. You will improve over time, and sometimes blog posts don’t need to have flowery vocabulary and complex sentences. Sometimes, the simpler a blog is written, the easier it is for the audience to consume.

If you’re scared that you don’t know enough…
Perhaps, you only know HTML, but you know more than someone who doesn’t know HTML. You will continue to grow and learn over time. You don’t need to wait until you get to a certain point because as technologists, we’re always learning. There will always be something that we don’t know.

If you’re scared of making mistakes…
Embrace your mistakes; they help you grow. I make mistakes all the time. Sometimes, I have grammatical errors in my blog posts or even technical errors, and someone corrects me. I learn from those mistakes and I’ve become a better writer, educator, and engineer as a result. Don’t aim to make mistakes, but when you do, know that everyone makes mistakes and it’s part of our journey to greatness.

If you’re scared that you don’t have time…
This is totally fair as we all have varying responsibilities and limited time. However, it is a worthy investment to reflect on what you’ve learned and share your knowledge with the world. If possible, work with your manager to carve out regularly scheduled time to write, and your blog posts don’t have to be long. They can be as short or as long as you want. You have creative authority over your content.

If you’re scared of criticism…
Remind yourself that you are writing for you. You are writing, so that you can look back and reflect on your growth. You are writing, so that you won’t have to repeatedly Google or ask your coworkers for help on the same questions. The harmful opinions of others don’t matter. You can always delete their comments or respectfully respond and continue to live life. I’ve found that people like to critique others when they feel threatened.

Keep a list of things you’ve learned

As you write code at your job, complete side projects, or contribute to open source projects, keep a running list of things you’ve learned.

I keep a list in my Notes app on my Mac computer and iPhone. It looks like this

### Idea list
Hack.Diversity

- How to negotiate salary
- Write thank you letters after interviews
- How to pass the technical interview
- How to learn / navigate a new codebase quickly 
- Tips for passing the CompTIA+ test
- Code
- Invite Automation
- Teaching to Empower: Supporting Early Career Devs
- Generate Social Cards with JavaScript
- From Code to Cloud — Git Emoji
- Build a Blockchain Simulation with JavaScript
- Make better pull requests
- Fuzzy Search Made Easy
- Overcoming the Fear of Contributing to Open Source
- How to Convince Your Boss to Open Source a Project
- Create the Perfect ReadME for your Open Source Project 
Small things I learned with code

- Linked issues
- Fusejs
- How to make a pull request template
- .github/.github/PULL_REQUEST_TEMPLATE.md
- https://github.com/open-sauced/.github/blob/main/.github/PULL_REQUEST_TEMPLATE.md
- .github
- Issue templates
- Forms yaml 
- Being autonomous
- Turning a Checkbox into a circle
- Handling routing with netlify
- Dependencies vs devDependencies
- React functions run on load or after
- Dealing with broken images in React 
- SEQA 
- Rendering components
- Using classList
- Invite automation
- Automatically generate a social image card
- Pull request template forms
GitHub ideas

- Prompt engineering tips with GitHub Copilot
- Lowering barriers with GitHub Codespaces
- Automatically install extensions with GitHub Codespaces
- Automatically install npm dependencies with GitHub Codespaces
- Automatically run your node app with GitHub Codespaces
- GitHub Actions extension
- Using GitHub Pages to federate your Mastodon identity 
- Building a to do list user interface with GitHub Copilot 
- Sending a toot with GitHub Copilot
- P5.js with GitHub Copilot
- I made a GitHub action with my voice
- I used AI to build AI
- How does GitHub Copilot help businesses

As you can see, my ideas range from simple concepts like "Converting a checkbox into a circle with CSS" to more advanced and creative concepts (like "Building a GitHub Action with my voice"). Some of the ideas are also repeated. Whenever I get an idea or one of my managers mentions that I should cover a topic, I write it down.
Keeping a list of ideas is helpful, so that when you want to write, you’re not also wasting energy and time, brainstorming topics.

Choose the topic you feel most excited about

It’s worth noting that I haven’t written about many of the topics listed above. I only write about what I’m most passionate about at the moment or most needed at my job (because this is my job). If it’s one of the ideas on the list, then I will write about it. However, if I have a random spark of inspiration, I will act on the idea immediately. On the other hand, I may also have to write about a topic requested by my coworkers, and I’ll focus on that. I choose the most urgent or the most exciting topic because that helps motivate me.

Also, consider granularity in your topics. If you want to write about a general topic, such as React, it would be difficult to write about every single concept of React. It would take a book or documentation to cover the entire framework. Instead, I suggest creating a general overview of React or picking a very subtopic such as, “Understanding the useEffect Hook” or “How I used React to build a blog”

Read other blog posts for inspiration

Before writing anything, I always read. Reading inspires my:

• Storytelling
• My writing style
• My choice of words and sentence structure
• My perspective
• My writing technique

By immersing myself in various texts, I can absorb different writing styles and techniques, allowing me to adapt and experiment with my own writing. Additionally, reading exposes me to diverse ideas and perspectives, broadening my understanding of the world and providing me with fresh insights to incorporate into my writing. It also helps me identify areas for improvement, such as refining my sentence structure or expanding my vocabulary. You don’t have to read a really long blog post or novel, but reading a quick paragraph is beneficial in refining my writing.

Determine your audience

Now that you know what you want to write about, and you’re inspired to write, it’s time to determine who you are writing for.

As humans, we have a tendency to want to write for everyone. We want to teach and help everyone, and that’s not wrong, but I wouldn’t suggest doing this for a blog post. I often talk with people who have goals around content creation, and they want to target junior engineers, mid-level engineers, and senior engineers simultaneously. If you try to reach everybody, you might end up creating a really long blog post that no one wants to read or you might overwhelm yourself and never actually finish the blog post. Trust me; it’s happened to me before and other technical writers. Even if I do finish it, the blog post ends up having every low engagement and it looks messy.

If you choose a very specific audience, then the other audiences will still benefit. For example, I’ve written blog posts for beginners, but sometimes senior engineers let me know that they still learned something new from the blog post or that they appreciated the way I broke down fundamentals.

The person I usually pick to write for is me, specifically past me. Here are examples:

• I wrote the blog post “Overcoming the fear of Contributing to Open Source” to myself when I was in a coding bootcamp and didn’t really understand open source.
• I wrote “How I used dev containers to enable GitHub Codespaces for ChatGPT” to myself as a GitHub Developer Advocate who was acting as “Customer Zero (well maybe customer 100)” on GitHub Codespaces.
• I wrote “How to speak at conferences when you’re scared of public speaking” to me in high school who was scared of public speaking.
• And I’m writing this blog post to myself before I ever wrote a technical blog post.

I have also written to my future self. Like, I often create advice for open source maintainers, but I only started maintaining a project in 2023. The advice I wrote in 2021 and 2022 is helpful for present day me.

Build an outline

Now, it’s time to plan what you write. Building an outline helps to align your thoughts in a way that readers will understand. Feel free to tweak the outline templates below, but this is what I use to write my own blog posts

Outline for “how-to” blog posts

If I’m writing a blog post guiding people step-by-step on how to do accomplish a task, I will use an outline like the one below:

Intro
- Hook
- Problem statement/What this solves for myself or readers

Step-by-Step Guide
1. Step 1
Optional: brief explanation of the step with supporting links for folks to learn more
2. Step 2
Optional: brief explanation of the step with supporting links for folks to learn more   
3. Step 3
...
N. Final Step

Conclusion
- Recap of the process
- Final thoughts or additional tips
- Call to action (e.g., encourage readers to try the steps and share their results/feedback)

Check out an example that follows this outline: How to send a tweet with GitHub Copilot

Outline for explainer blog posts

I define an explainer blog post as a blog post that explains a topic, but it doesn’t necessarily walk people through accomplishing a task. The main purpose is for readers to get an introduction to a concept.

Intro
- Hook
- Brief overview of the topic and why care

Body
1. Key Concept 1
    - Definition/explanation
    - Examples 
    - Importance or relevance
2. Key Concept 2
    - Definition/explanation
    - Examples
    - Importance or relevance
3. Key Concept 3
    - Definition/explanation
    - Examples
    - Importance or relevance
...
N. Final Key Concept
    - Definition/explanation
    - Examples
    - Importance or relevance

Conclusion
- Summary of the key concepts
- Closing thoughts or implications
- Call to action (e.g., encourage readers to explore further or ask questions)

Here’s an example of a blog post that follows this outline: Why are people developing in containers?

Outline for thought leadership/opinion blog posts

These types of posts are posts where I just share my opinion on the direction that industry is going. Many times, I use it to create productive conversation and share my leadership skills.

Intro
- Hook
- Brief introduction to the topic/opinion and why it matters to me

Body
1. Supporting Point 1
    - Explanation of the point
    - Supporting evidence or examples
2. Supporting Point 2
    - Explanation of the point
    - Supporting evidence or examples
3. Supporting Point 3
    - Explanation of the point
    - Supporting evidence or examples
...
N. Final Supporting Point
    - Explanation of the point
    - Supporting evidence or examples

Counter arguments (optional)
- Address potential counterarguments or opposing views

Conclusion
- Reinforce the opinion and provide a call to action

Here’s an example of a blog post that follows this outline: The Hard Parts of Developer Advocacy for me

Outline for listicle blog posts

These are posts that are often written in list format. The reason they’re written this way is to make the concept fun, quick and easy to consume for readers. These types of blog posts are often have titles to the ones below:

• Top Ten Tips for…
• 5 Must-Have…
• 7 Amazing…

Intro
- Hook or intriguing statement related to the topic
- Brief introduction to the theme or subject of the listicle

Listicle Items
1. List Item 1
    - Explanation 
    - Example
2. List Item 2
    - Explanation 
    - Example
3. List Item 3
    - Explanation
    - Example
...
N. List Item N
    - Explanation
    - Example

Conclusion
- Final thoughts or insights
- Call to action (e.g., encourage readers to share their favorite item or suggest additions to the list)

Here’s an example of a blog post that follows this outline: 8 things you didn’t know you could do with GitHub Copilot

Take a shower

This is an odd suggestion, but I do my best thinking in the shower. I think the sound of running water helps me to focus on my thoughts. In the shower, I can write a whole blog post in my mind. Besides taking a shower, you can try other activities that can stimulate your mind:

• Walking
• Jogging
• Listening to music
• Meditating

Enter a flow state for writing

Disable all distractions and start writing. I strongly recommend that you don’t edit as you write. I find that disruptive for my flow. I fill out each part of the outline that I created in whatever order that I prefer. I write the way I speak, and I just keep going. After I’ve written all my thoughts on paper, I will start editing.

My editing process consists of deleting irrelevant paragraphs, fixing spelling mistakes, and removing unnecessary punctuation marks. I’m a super light editor. I feel that if I edit it too much or spend too much time perfecting my blog posts, then I will never press publish. In the following paragraphs, I expand a bit more on my editing process. However, the way I look at it is, I want to get my thoughts out there. Once I do, someone will reach out to me – like my job and ask for a more refined version of my blog posts. Then, I could use resources my job provides me like professional editors to improve my blog posts.
Also, I recognize that it doesn’t matter how much I edit; my blog post will always need more editing. It’s like code – there’s a bug somewhere. Sometimes, I just edit it after I publish. Often, people message me to say that I spelled a word wrong, and I usually update it afterwards.

It’s no big deal. Write for completion rather than perfection.

Struggle with writing? Record your voice

There are some people who find writing difficult, and that’s okay. Brian Douglas told me about a tip that could help folks who struggle with putting words on a paper: speak. Record yourself speaking, upload the audio to your computer, and use a tool that can transcribe those words.

The tool I suggest is Descript. It does a great job of transcribing audio. It may have a few mistakes here and there, so double check what it generates and make small edits.

Read it aloud (or use a Text-to-Speech reader)

Reading my writing aloud enhances the quality of my content. When I read text I wrote in my head, I may notice particular issues, but reading aloud allows me to:

• Improve the clarity and flow
• Enhance the tone and voice
• Spot grammatical and stylistic errors
• Evaluate the rhythm and cadence of my content
• Assess the audience appeal
• Sometimes, I'm too lazy to read my writing aloud or I’m struggling to focus, so I use a text-to-speech reader like, Natural Reader.

Use a digital writing assistant

Digital writing assistants like Grammarly find errors you might have missed. Word Tune is another tool that I find helpful. It’s great because it takes my hard-to-understand sentences and converts them into clear, terse sentences. ChatGPT is another tool, but this one is a little more controversial. While I don’t encourage folks to use it to write whole articles, it does give great feedback. I’ll often prompt ChatGPT with the following:

• What did I do well in this blog post?
• What didn’t I do well in this blog post?
• Can you help me come up with a better title for this blog post?

Share your draft with stakeholders to gather feedback

I received this advice from Kurt Kemple: Share a draft of your blog post with people at work who asked you to write the blog post (product managers etc) AND someone from your target audience. When I follow this advice (because I'm lazy), I always get a high level of engagement and a quality final product. For example, I wrote this blog post called, “How do I resolve merge conflicts?” I shared the draft with my friend Nathan, who recently graduated from a coding bootcamp. Nathan’s feedback helped me ensure that beginners could understand my blog post, too!

Add a cover image

In addition to well-written content, adding a cover image to your technical blog posts can significantly enhance their appeal and engagement. Don’t ignore this step. Including a cover image demonstrates your commitment to presenting your technical content in a professional and polished manner. It shows that you've put thought and effort into crafting a visually appealing and well-designed post, which can elevate your credibility as a writer and technical expert.

I’m not an artist nor am I great at design. I often use the following tools to help me create an image like:

• Canva
• Figma

I’ve also seen folks like Bekah H.W. and Brian Douglas use Midjourney to create cover art. I believe my friend Mayank uses Excalidraw to create cover art.

Several of my covers images aren't that cute, but here are a few that I think look great:

Publish

Publish your blog post on the platform of your choice. You can use:

• DEV
• Hashnode
• Free Code Camp
• Medium
• Or your personal website

You can make the decision on where you want to post based on your target audience and how you want to own your content. I sometimes use a platform called BloggU to cross-post on multiple platforms.

Share it on social media

Congratulations, you posted the blog, but you’re not done yet. Share your post with others helps the post gain more engagement. Sometimes, I receive messages from folks I’ve never met before that my blog post was helpful for them. Social media enables me to reach folks worldwide. I try to share my blog posts on:

• Twitter
• Bluesky
• Mastodon
• LinkedIn
• Discord
• Sometimes I share posts with my coworkers on Slack (could be cringe, but no one is going to know that I created these things if I don’t tell them)

I try not to announce things in a self-centered way. You can if you want to, but I want to show that my intentions are to share knowledge and grow rather than be at the center of attention. So I might add a small blurb that says something along the lines of: “Hey y’all! I used to struggle writing blog posts, but now I’ve gotten the hang of it, so I wrote a blog post to help others develop a good strategy, too. Check it out and let me know your thoughts.”

Additional Resource

The Developer Advocate’s Guide to Content Creation by Kurt Kemple

Conclusion

Writing technical blog content is not easy, but I’m hoping the above steps can help you to stay in the flow and create content that you’re proud of. Again, I want to emphasize that we’re not striving for perfection. This blog itself is far from perfect, but it accomplishes two things:
If I ever forget my process or I’m feeling impostor syndrome, I can always re-read this post as a reminder
It helps aspiring technical blog writers to level up their careers

Call to action

I would love to hear about different writing strategies to improve your blog content or anything that I listed that’s been helpful to you. For more content like this, follow me!

Stay cool, friends 😎