Advice of 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 heardScott Hanselmansay atWe Rise Confin June: we only haveso many keystrokes leftto 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 readmy writingbefore, 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 likedata as storytelling. I was hooked, and hastened to write myfirst article.

Upon becoming aClarifai Championin the fall of 2016, I challenged myself to write more about code. I created a well-receivedbeginner’s guide to open source, and followed up with mystep-by-step dynamic programming tutorialthis summer.

Since August 2016, I’ve written a total of 10 technical writing pieces, and recently announced anew 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 createdmy own. I studied dynamic programming quite aggressively to succeed in my algorithms class, so I wrote abouthow 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 likehow 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.

I got a lot of traction as a technical writer by getting pieces accepted infreeCodeCamp, which is one of the biggest technical writing publications on Medium with ~300,000 followers. I sometimes publish my writing ondev.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!

Source: https://dev.to/alainakafkes/tackling-technical-writing