Why Every Developer Should Know a Bit of Technical Writing
By Larry Alton

Most software developers love their craft, and spend hours not just writing code and solving problems, but actively engaging with the community and trying to learn new things. Software developers want to constantly get better, improving their abilities, staying up-to-date with the latest trends, and hopefully making more money.

But improving your knowledge of programming isn’t the only way to improve your abilities as a software developer. Most developers see an enormous benefit in learning related skills—especially technical writing.

What Is Technical Writing?

Technical writing is a form of communication that attempts to take a technical field (like programming or software development) and convey ideas from that field as efficiently as possible, sometimes to other experts, and sometimes to non-experts. Technical writing draws upon traditional writing skills, but has slightly different demands; you’ll often be dealing with more challenging descriptions, or technical terminology that may or may not make sense to your audience.

Tools like ClickHelp exist to make technical writing easier, especially if you’re trying to create user guides, but it also takes practice and patience to perfect the art.

Why Technical Writing Helps Developers

So why should software developers try and learn technical writing?

  • In-team communication. First, technical writing can help you communicate more easily with your teammates. If you’re collaborating with other software developers on a regular basis, you know the importance of exchanging ideas, ensuring you’re working for the same high-level goals, and solving problems together. Technical writing abilities help you formally structure these bits of communication so your coworkers can better understand them; with an efficiently written message, you can avoid most misconceptions and ultimately work faster.
  • Out-group communication. You can also use your technical writing abilities to communicate with out-groups more efficiently, especially if those groups have limited technical knowledge. Rather than using terms unique to the development field, or describing code directly, you’ll have to find high-level ways to describe the challenges you’re facing, or use metaphors so that other people can grasp what you’re saying. Either way, you’ll be more valuable in client meetings, and you’ll be able to talk to account managers and team leaders in other departments in a way that makes sense to them, while still conveying what you need to convey.
  • Problem solving and internalization. Developers are problem solvers, so it’s important to have as many problem solving tools in your toolkit as possible. You’ll be forced to come up with creative ways to accomplish what was previously impossible, find creative ways to utilize past breakthroughs, and eliminate those pesky bugs that don’t make logical sense. Technical writing forces you to get into the habit of putting abstract concepts into understandable words; it broadens your vocabulary, and in some ways changes how you think about the world. You may not realize it right away, but this change in mindset will be invaluable in how you conceptualize and deal with technical problems (not to mention communicating those problems to others).
  • Help guides and documentation. On a more straightforward level, technical writing is a useful skill in creating help guides and other forms of documentation for the software you develop. As you develop new features and integrate them into your core product, you can describe them in a way that makes sense to users, and guide them through some of the pain points they might experience along the way.
  • Software design and user empathy. If you have a hand in coming up with high-level concepts for the software, or tailoring ideal features into something that’s usable, technical writing can also give you a better sense of user empathy. After writing in a way that makes technical terms easier for end users to understand, you’ll have a better idea of what makes sense to an end user–and you can design your software around it.
  • Career value (and future options). Technical writing makes you a more valuable employee or vendor, possibly earning you a raise if you can implement the skill appropriately. It also gives you a future career option in technical writing, should you ever lose interest in software development.

With those benefits in mind, it’s time to try your hand at improving your technical writing abilities. There isn’t a single convenient place to start, so begin the process by outlining your goals and paying more attention to how you communicate (both with teammates and non-experts in your field). Read the work of other technical writers and programmers in your field, and adopt some of the phrasing, formatting, and patterns they use that seem to be the most effective.

Over time, you’ll become more comfortable with technical writing, and you’ll start to write (and speak) more effectively. Be patient; this is a process that could take years to flourish.

Larry Alton is a professional blogger, writer, and researcher who contributes to a number of reputable online media outlets and news sources. A graduate of Iowa State University, I’m now a full-time freelance writer and business consultant.