If you’ve read any of my posts, it’s obvious I’m not much of a writer. I’m pretty comfortable and confident writing code; I just sit down at the keyboard, and the code flows. Even if it’s a new language, I can generally pick it up and get moving pretty quickly. When it comes to writing in plain English, however, the words just don’t come.
It happens a lot, both at work and for side projects: I’ll have just written a bunch of code that I’m proud of, but then comes the time to share that code with others. Either I need to explain the code in a PR, an email, or technical documentation. Even though the code came easy, when I start to write about the code, I’m stuck.
You may be asking, “If you have such a hard time with technical writing, why on Earth are you torturing yourself by keeping a technical blog?”. The short answer is that if you don’t practice a skill, you’ll never get better at it. For the longer answer, read on.
I read Malcolm Gladwell’s Outliers a few years back, and there is one idea from the book that has really stuck with me. Gladwell claims (pretty convincingly, I think) that mastery of any skill requires 10,000 hours of practice. Moreover, all those people that seem to be naturally talented at something, have in fact, put in countless hours of unseen work to get to where they are.
After reading Outliers, I can say, personally, I don’t feel like I’m “talented” at many things. Any skill I claim to be good at, I have had to work for. Over my career, I think it’s fair to say I’ve put in my 10,000 hours of writing code, and I think it shows, at least in some ways. I can confidently sit at my keyboard and code away, and most of the time it feels effortless. On the other hand, I’ve come nowhere close to having spent 10,000 hours doing technical writing, and that shows as well. I spend too much time trying to put my thoughts into words. It’s hard to come up with the right way to explain complex technical concepts, and it’s hard to structure a document for ease of consumption.
But it’s getting easier. The more technical posts I make on here, the more comfortable I feel in writing technical documents and the more confident I feel in sharing my thoughts with others. And I’m sure by the time I’ve hit my 10,000 hours, it’ll feel like second nature.
That brings us to reason number one for having your own blog. Maintaining a technical blog will improve your communication skills.
We all know the programmer stereotype: a person in a hoodie sitting in a dark room typing away into a dark-themed IDE with no other signs of life. The stereotype tells us that if you’re a good enough programmer, you don’t need anyone else’s help. You can write a ton of code, you can write it well, you can write it quickly, and you can write it by yourself.
But we all know that’s fantasy. No one ever works in a vacuum. In real life, building software often (but not always, apparently) requires teams of people. Even if you’re working all alone on a pet project, you’re not actually doing it alone. You’re likely working with libraries built on top of libraries built on top of other libraries written by someone else (who probably also wrote some technical documentation accompanying the code). That’s just the nature of software. Many systems are just too complex for a single person to fully understand. So, like it or not, we must work in teams. And to work effectively in a team, you must communicate effectively.
In today’s world, with such a large portion of developers working remotely and across different time zones, often the only practical (and most inclusive!) way to communicate is asynchronously. When you can’t fall back on in-person meetings to share your ideas with colleagues, writing is the next best thing – It’s arguably better since you have the time to really flesh out your ideas and decide on how to best present them. You may write an email to a colleague on the other side of the world, you may write a technical document to describe your idea for an architectural design, and probably most commonly, you may describe the code changes you’re proposing in a pull request.
To get your ideas across clearly, all of these mediums require you to be a good writer. Regardless of what form your technical writing takes, it is an important skill to have as remote work continues to grow in popularity.
Blogging is one of the easiest ways to put in your 10,000 hours to achieve mastery. But that’s not all blogging can do for you…
Blogging can also help us solve one of the age-old problems in software. It can help us avoid re-solving the same problem over and over.
For me, this used to happen all the time. I’d spend days trying to figure out why something I wrote wasn’t working. Then I would come to find out there is this arcane trick to get it to work again. I would implement the weird fix, then, satisfied that it’s working again, move on to the next task and forget everything I just learned. Two months later, I run into the same problem again, but by now I’ve forgotten all about my solution, how I found it, and where to even start looking.
After going through this cycle of problem->research->solution->forget->problem an embarrassing amount of times, I realized that keeping a notebook of useful tidbits could help. I started jotting down little notes about what I did when tackling tricky problems. The idea was that any time I got stuck on a problem in the future, I could just skim through my notes and see how I solved the problem in the past.
Unfortunately, those fell short as well. After writing a year’s worth of notes, they were no longer easy to search, and even when I found what I was looking for, often the brief descriptions I left myself weren’t the least bit helpful out of context. (Who knows what “Don’t re-[illegible] the object” means?)
These days, when I run into tricky problems, I still make notes about them, but then shortly after, I try to write up a more in-depth personal wiki entry about them (especially the really tough ones). After a little bit of revision and clarification, many of those eventually find their way onto here as posts.
By taking the time to write up my notes as blog posts, I am re-enforcing what I have learned, and I’ve given myself a way to easily search for solutions to the problems I’ve already solved.
Chances are, if you’ve had a hard time solving a specific problem, there are others who will go through the same thing. The really beautiful part about a blog is that it is inherently public, so it benefits the entire community.
Think about it. As a developer, how often do you turn to Google to figure out how to do something new. How often has someone else’s post helped you out of a tough spot? Without the Internet, we developers would be almost useless. If we’ve all benefited from the hard work of others, why shouldn’t we give back to the community ourselves? In the same way open source software allows us to focus on the interesting code and not on the implementation details, so too shared knowledge allows us to focus on solving interesting problems by reusing that which has already been learned by others.
Now this is a delicate balance. Yes, by sharing our knowledge online, we are helping the community. At the same time, though, we’re probably not going to become famous through our blogs. I, admittedly, don’t get very much traffic on this site at all, and that’s ok. While I’m not helping tons of people, I am helping some, and that’s all that matters.
It genuinely takes a decent bit of work to regularly make posts (I’m not even sure you can call what I do regular), and the pay-off isn’t immediately obvious. But I assure you, it is worth it in the long run. I refer to my own posts every now and then when I’m trying to re-solve a problem. Moreover, I do get some visitors on the site, so I’m not the only one benefitting. Finally, even after a short period of time, I feel like my communication skills are starting to improve, and I actually find myself enjoying technical writing.
I hope this post has helped kickstart you into share your knowledge online, but you’re probably left wondering where to start. If that’s the case for you, I’m working on a follow-up post explaining how I got started with this website and all the options available for creating one for yourself.
I’ll update this post with a link once the next one is finished. In the meantime, bookmark this page to keep an eye out for the next post, or subscribe to my RSS feed to get notified when it comes out.
Are there some reasons I missed? Do you disagree? I’d love to hear your thoughts on blogging. Feel free to discuss in the comments section below.