Tackling Technical Writing

I recently received a request from a reader for technical writing advice. As I sat down to respond, I thought back to something I heard Scott Hanselman say at We Rise Conf in June: we only have so many keystrokes left to type in our lives, so we may as well use them effectively. Why not share what I’ve learned from technical writing to a greater audience?

If you’ve never read my writing before, here’s a quick backstory.

Though I’ve been an avid writer since the days of elementary school, I got into technical writing when I found out about Medium last year. The first pieces I read weren’t about code per se, but they covered subjects like data as storytelling. I was hooked, and hastened to write my first article.

Upon becoming a Clarifai Champion in the fall of 2016, I challenged myself to write more about code. I created a well-received beginner’s guide to open source, and followed up with my step-by-step dynamic programming tutorial this summer.

Since August 2016, I’ve written a total of 10 technical writing pieces, and recently announced a new blogging initiative. I’d like to share five takeaways that I’ve learned from my year of technical writing.

(1) Break things into steps or sections.

Every technical blog post I’ve written is broken down into smaller pieces to make it more digestible to an audience with a short attention span (aka most of us on the Internet). This way someone can skim through your blog post and determine if it’s in their best interest to read it. Similarly, section headers can help a reader easily bookmark where they left off in your piece.

(2) Write about how YOU solved a technical problem.

I couldn’t find a comprehensive resource for getting into open source, so I created my own. I studied dynamic programming quite aggressively to succeed in my algorithms class, so I wrote about how I solve problems that require dynamic programming. Writing about what you learned while solving a technical problem is never a waste of words because it documents your growth, confirms your understanding, and provides a resource for future learners. Your technical writing will be more detailed and empathetic if you’ve been in the shoes of your audience!

(3) Don’t feel pressured to write only about code.

I’ve written about “softer topics like how reading books can benefit engineers, which is a contender for my favorite technical blog post that I’ve ever written. You could write about a subject that matters to people in technology – such as takeaways from a conference, lessons learned in a first job, or thoughts on technical speaking – and it would still be worthwhile technical writing. Remember, not all of us are software engineers.

(4) To gain an audience, leverage popular technical writing platforms.

I got a lot of traction as a technical writer by getting pieces accepted in freeCodeCamp, which is one of the biggest technical writing publications on Medium with ~300,000 followers. I sometimes publish my writing on dev.to, a technical writing platform that will tweet out your piece if they find it interesting, thereby reaching an audience of ~125,000 followers. By publishing in these and other well-known places, I gained more readership than I would have in my own network.

(5) Ask friends to look over your work!

Behind every great technical writer is a team of proofreaders. Before you hit publish, it’s helpful to see how a few friends respond to what you’ve written. Does it make sense? Is it too wordy? Are there grammatical errors? Although any good friend will be inclined to think highly of your work, probe them for any mistakes, weak arguments, or other problems in your blog post. Criticism is more easily taken from a friend than a stranger on the Internet, and more easily resolved before you publish.

These five tips have helped me write some pretty cool stuff over the past year, and I’m looking forward to my future technical writing endeavors. Now it’s your turn to try out technical writing. So get out there and whip up that blog post idea that’s been on your mind!

Enjoy what you read? Spread the love by sharing this piece. Have thoughts or questions? Reach out to me on Twitter or in the comments below.