Tackling Technical Writing
Tags: technicalwriting, writing, developerevangelism, advice
Published: 2017-08-18 14:23:39

---
title: Tackling Technical Writing
published: true
description: Takeaways from a year of typing up technical blogÂ posts
tags: technical writing, writing, developer evangelism, advice
cover_image: https://thepracticaldev.s3.amazonaws.com/i/fe71wcw88haahs15hgb9.jpg
---

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](https://www.hanselman.com/) say at [We Rise Conf](https://werise.tech/) in June: we only have [so many keystrokes left](http://keysleft.com/) 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](http://alainakafk.es/#/words) 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](https://medium.com/@lamthuyvo/you-and-me-as-data-points-958ed4723f51). I was hooked, and hastened to write my [first article](https://medium.com/ladies-storm-hackathons/the-gender-gap-as-told-by-data-71dfce420519).

Upon becoming a [Clarifai Champion](http://blog.clarifai.com/clarifai-champions-round-2-meet-our-newest-future-developer-evangelists/#.WZb2FxJSyRt) in the fall of 2016, I challenged myself to write more about code. I created a well-received [beginner’s guide to open source](https://medium.com/clarifai-champions/99-pr-oblems-a-beginners-guide-to-open-source-abc1b867385a), and followed up with my [step-by-step dynamic programming tutorial](https://medium.freecodecamp.org/demystifying-dynamic-programming-3efafb8d4296) this summer.

Since August 2016, I’ve written a total of 10 technical writing pieces, and recently announced a [new blogging initiative](https://alainakafkes.github.io/chronicles/about/). 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](https://medium.com/clarifai-champions/99-pr-oblems-a-beginners-guide-to-open-source-abc1b867385a). I studied dynamic programming quite aggressively to succeed in my algorithms class, so I wrote about [how I solve problems that require dynamic programming](https://medium.freecodecamp.org/demystifying-dynamic-programming-3efafb8d4296). 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](https://medium.com/@alainakafkes/on-literature-linked-lists-6730308a0d81), 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](https://medium.freecodecamp.org/), which is one of the biggest technical writing publications on Medium with ~300,000 followers. I sometimes publish my writing on [dev.to](https://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](https://twitter.com/alainakafkes) or in the comments below._