This post was written by Vaidehi Joshi. Vaidehi is a writer turned programmer. She is a Barnard College alumna and graduate of The Flatiron School. Before learning to code, she was a professional Urdu student and a sixth grade teacher. You can stay up-to-date on the amazing things she's learning at her blog, Words and Code.
There's one thing that every programmer does, regardless of his or her skill level: Google for stuff. Sometimes that leads us to find helpful documentation, or a Stack Overflow post written by someone who had a similar problem. But if we're really, really lucky, we find something even better in our internet-searching adventures: a great blog post.
Great technical blogs are treasure chests hidden deep within the depths of the internet ocean — we all desperately search for them, but they're difficult to actually uncover. Part of this is, of course, the fact that not enough programmers maintain technical blogs. And it's understandable why.
Blogging can be torturous. It takes a lot of discipline to actively sit down, think through a concept, and write a single blog post. And if you're crazy enough to commit to writing a weekly technical blog like me…well, you probably spend at least one night of the week surrounded by programming books, wracking your brain to try and understand how something works, just so that you can write about it for someone else.
Yet despite the amount of effort it requires from you, I believe that technical blogging is one of the best things you can do not only for yourself as a developer, but also on a larger scale as a member of the programming community.
A Different Kind of Contribution
When most developers talk about open source contributions, they're usually referring to their pull requests and GitHub issues on a gem, framework, or side project. And while this may be a more exciting way make an open source contribution, it's certainly not the only way to give back to the programming community.
Blogging might not seem as thrilling as giving a technical talk or writing a test for a framework's new feature, but it's a contribution that's both severely lacking and desperately needed in our community.
As more and more people learn how to code, they'll all start to run into the same problems. Most of the time, these problems are issues of understanding a language's syntax or grasping a more complex, computer science concept. More seasoned developers have probably already solved these problems, and have a strong conceptual understanding of what causes them.
The problem is, even though so many developers understand the concepts and syntax of a lanugage, not all of them write it down. They might mention it in passing to another developer, but their knowledge doesn't exist in a place that's easily accessible by anyone else. This is of particular disservice to younger developers who might not have access to resources. For some self-taught developers, StackOverflow answers and painful Google searches are the only viable options and often, that simply isn't enough.
But it's not just experienced programmers who should blog; junior developers can contribute just as much. Whether you're writing about a complicated system or a series of methods on a data structure, the odds are high that someone else has discovered the same thing you have discovered, and that someone else will one day struggle with the same things you are struggling with now.
By writing about the things that you learn about, find interesting, or simply don't understand, you aren't just teaching yourself — you're also helping share your knowledge with every person who reads your post, whether they click on your post through an act of curiousity or a form of sheer desperation.
To Serve And To Self-Serve
It's deeply satisfying to know that someone else has read and benefited from your blog posts. However, technical blogging isn't just for other people. It's for you, too. Or, more specifically, it's for the future you.
There will ultimately be a time when you'll remember writing about how a method or a module works, but you can't remember the exact rules or syntax behind its functionality. Luckily, you'll have your blog post to refer to and remind you of what you tried and what worked and what didn't. The blog post you write today may very well save you hours of looking up documentation and rummaging StackOverflow posts tomorrow.
Technical blogging can also be beneficial in subtler ways. When written frequently enough, blog posts can serve as a kind of diary of your technical growth. As you get better at programming, the problems you try to solve will become more complex, and the technical challenges will inevitably become more difficult. Keeping a technical blog can be a great way of documenting your growth as a developer.
This documentation can be particularly useful on a professional level. All software companies want to hire smart, thoughtful, communicative developers who can easily assimilate into a team, and who are ready to both teach and learn. Your technical blog is empirical evidence of all of these qualities.
By reading your posts, potential employers can see not only the clarity and quality of your code, but also how you've grown as a developer, how you think through problems, and how well you're able to communicate them to an audience who may be unfamiliar with them. The quality of your writing not only demonstrates how well you can explain a concept to someone else, but also shows how well you can teach yourself and learn something that's entirely new to you.
Habits of Highly-Effective Blogging
Knowing all the reasons we all ought to blog, only one question remains: what makes an effective blog? There are a lot of different opinions on how to write a good technical blog. I am by no means an expert on the topic, but over the past few months of weekly blogging, I've come up with my own structure for technical writing:
1. Introduce the problem
Whether you're writing a short story or writing a small Ruby class, all writing is nothing more than a narrative. Set the scene for the topic you learned about or the new discovery you made. A great way to start writing is by picking something you don't understand at all, and then teaching yourself as much as you can about it. In any case, explain how you stumbled on the problem you will attempt to solve.
2. Explain how you found the solution
Many blogs generously implement code snippets. In fact, I'm a big fan of code snippets myself. But blocks of code aren't what make a technical blog — it's the explanation that goes alongside it that makes all the difference. When you write about how you solve your problem, make sure you're actually writing about the solution, and not simply putting it in a code block for the reader to figure out on his or her own. A thoughtful, empathetic paragraph explaining a concept can mean the difference between a new developer understanding your post or leaving the page feeling utter frustration.
3. Unpack and explore how it works
This is a bit more rare, but it's exactly what differtiates a good blog post from a really great one. Diving into the basics of what you learned is something that will benefit a reader of any skill level. Not only does it show a deep understanding of a concept, but it also reinforces the fundamentals of programming, which is something that even the most experienced developer will appreciate in your writing.
4. Be yourself
Some people will read your blog out of necessity, while others will read from a place of curiousity. In either case, you want your personality to shine through the words. Be genuine and kind to your reader, and write as though you're telling them the story of how you learned this thing. Not only will it make them want to keep reading your writing, but it'll also give your technical blog a unique voice from all the others.
No matter what approach you take when it comes to technical blogging, one thing is for certain: technical blogging will impact both you and your community in a variety of ways. It might be hard work at first, but the benefits are certainly worth it. And who knows, if you blog enough, you might even get to see your blog post shared with tens of thousands of other developers on Ruby Weekly! You'll have to trust me when I tell you that never, ever stops being super cool.
