Uncategorized
Guest posts / Media

Developer Vaidehi Joshi will convince you to start a technical blog

Keep reading.

Vaidehi Joshi gives a talk on technical blogging at BrooklynJS. (Courtesy photo)
This is guest post by Brooklyn-based developer Vaidehi Joshi, which she adapted from talks she's given at ELA Conf and BrooklynJS. Find her blog here.
We’ve all heard that blogging is important.

Many of us have been saved on a late night or under a tight deadline by a well-written technical blog post. And most of us have been told that we should write more blogs. But how many of us actually follow through on writing down what we learn, much less maintain a regular technical blog?
I didn’t. Until recently.

###

Learning something new is always hard.

But programming, in particular, forces you to come face to face with the internal struggle that comes with learning: that feeling that you have no idea what’s going on — and that you will never understand it.
I didn’t always love programming. Before I made the jump into tech, I was a writer. I learned to code at The Flatiron School, a programming bootcamp in New York City. Flatiron was a wonderful place to confront the struggle that comes with learning because I was surrounded by other people who were going through the exact same thing, too. We were all in over our heads, but somehow never really felt alone in it.
But after twelve weeks, we left the safety of the school and went out in pursuit of our first programming jobs. And that’s when that feeling kicked in again, this time in full force.
At my first developer job, I spent most days feeling incredibly overwhelmed. I was working at a software consultancy in Baltimore called Friends of The Web, where some of my team had been coding for fifteen years and knew so many things that I didn’t. But, after a few months of trying to keep my head above water, my goal changed from trying to survive in tech to aiming to thrive in tech. I focused on trying to level up as much and as fast I could.
I started writing things down. I wrote down all the things that I had debugged, all the things that I didn’t comprehend, all the things that I built and all the things that I needed to go home and Google with a glass of wine.

The internet is a wide and wondrous place but it lacks well-written technical blogs.

Eventually, I had tons of nonsensical pages and notes on concepts that I knew a little bit about but didn’t fully understand: a list of all the things that I wanted someone to teach me, a table of contents for the many things that I knew I need to read more about.
The internet is a wide and sometimes wondrous place, filled with cat gifs and threaded tweets. But despite how many dog Vines it houses, it lacks well-written technical blogs — especially those that are beginner-friendly. I couldn’t always find blog posts explaining things on my list, and even when I did, I had a hard time understanding them. I decided to take everyone’s advice and turn my list of things to learn into a technical blog. I promised myself that I would write a technical blog post, every week, for an entire year. So I did.
Read the blog
It turns out that the concepts that I struggled to learn were topics that other people struggled with as well. In the first few weeks of writing my year of technical blog posts, I was worried that no would was reading what I was writing. Even worse: I was worried that no one ever would.
But somewhere along the way, they did. And I think the crux of it is simple: human beings love stories. In my year of writing technical blogs (which involved reading a lot of other people’s’ technical blogs), the ones that resonated with me were the ones that told a story.
Some storytelling advice from George Saunders. (Courtesy image)

Some storytelling advice. (Courtesy image)


Good technical writing is nothing more than good storytelling. The trouble is, writing isn’t always the most glamorous way of leveling up in tech. There are so many ways to give back to the community and get better at what we do: organizing conferences, giving talks, contributing to open source. Technical blogs often get overlooked and left out of that list. But I don’t think that they should. In fact, I they should be at the top of that list.

Maintaining a technical blog is one of the best ways to invest in your career.

Here are a few reasons why:

  1. Blogs are a way of documenting your thought process, particularly when it comes to debugging. You can look back at the problems you’ve solved, how you solved them and more importantly, how you thought through them.
  2. Blogs show that you are good at communicating, which is something companies love to see in potential hires. A good technical blog is a great example of your ability to learn yourself something new, and then teach it to others.
  3. Blogs track your growth. They are self-documenting in the most literal sense: you can see all the things that you have learned and created and overcome when you look back at a blog post from even just a year ago.

But technical writing isn’t all self-serving. It’s beneficial to others and to the tech community at large. Good technical blogs act as supplemental documentation for open source frameworks or libraries, and are helpful to project maintainers who may not have had the chance to write documentation of their own. Blogging has immense impact, especially for those people who are self-taught, who may not have a computer science background, or who may be making a career switch and stumble upon a well-explained blog post when they’re really stuck. Technical blogging makes room for more voices to come to the forefront of our industry, which desperately needs more storytellers.

One of Vaidehi Joshi's slides for a talk she gave on the same topic.

That last one tho. (Courtesy image)

So the question now is hopefully just this: how do you know what to write?

The saying for writers has always been “Write what you know.” I think the equivalent for technical writers is something along the lines of “Write what you didn’t know.” That is to say, write about things that you didn’t know once and now do, things that you still want to learn, things that you have built, things that you stumbled upon recently and maybe didn’t even know how to solve. Write, as Kurt Vonnegut once said, “to please just one person.” I find it helpful to write to one person and have a conversation about the problem as I unpack and explore how it works.
And even if you do all of that, there’s still a chance that no one will read what you’re writing. But there’s also a chance that, if you write empathetically and with humility, you could teach someone on the other side of the world about something that they never knew before.

Series: Brooklyn
Engagement

Join the conversation!

Find news, events, jobs and people who share your interests on Technical.ly's open community Slack

Trending
Technically Media