The Ultimate Guide to Writing Technical Blog Posts

 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.

https://hackmd.io/@alexaa34/BkS5ectRZl

https://medium.com/@alexharris59600/the-ultimate-guide-to-writing-technical-blog-posts-47ee067d3a8f

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.