Programming is technical writing

by Jason Swett,

I enjoy reading nonfiction. Not just programming but also biology, physics, philosophy, mechanical engineering, robotics and other technical topics.

The challenge in technical writing is to convey difficult ideas in ways that are easy to understand. The best technical writing doesn’t make the reader think, “Wow, the writer must be a genius to be able to understand this stuff,” it makes them think, “Wow, I must be a genius to be able to understand this stuff!”

Very few programmers make a serious study of technical writing. I myself, 20+ years into my programming career, have only just begun to do so myself. But I think improving one’s technical writing ability is a highly profitable undertaking for any programmer, even if you never intend to do any technical writing. In a very real sense, programming IS technical writing.

Donald Knuth has said, “Programs are meant to be read by humans and only incidentally for computers to execute.” When we write code, we’re (hopefully) aiming not just for it to fulfill its functional requirements but also for it to be understandable by human readers. In other words, we’re trying to convey difficult ideas in ways that are easy to understand. That’s what I mean when I say that programming is technical writing.

How does one get better at technical writing? One thing that helps is to do a lot of technical reading. In programming, my favorite technical writers are Martin Fowler and Steve McConnell. Outside of that, my favorites include Richard Dawkins (the master in my book), Carl Sagan (a close second), Steven Pinker, David Deutsch, Sean Carroll and Richard Feynman. If you’d like a specific starting point, I’d recommend The Blind Watchmaker by Richard Dawkins.

One last comment, an important one. Good writing is downstream of good thinking. None of the authors I listed above are writers by profession. The programming authors are programmers and the science authors are scientists. These writers are good writers because they’re excellent practitioners, with good ideas worth sharing. It also so happens that these practitioners have learned how to skillfully put their ideas into words. If Richard Dawkins were a clumsy writer, his books would probably still be worth reading on the merit of the ideas they contain. But if Dawkins were an excellent writer but a poor scientist, his books would be junk. Similarly, a programmer must be skilled not only in coding style but in designing and maintaining a software system. Good code is downstream of good thinking.

Leave a Reply

Your email address will not be published. Required fields are marked *