Writing in Code

I am a computer nerd. It’s not something I have in common with most other technical writers I know. Most of the writers I know come more from art than science, whereas I’ve come to approach my work from the opposite perspective. But lately I’ve been thinking it’s a bit of a shame that so few other writers seem to share that perspective. Particularly because I now see technical skills, especially programming, as a sort of secondary writing skill that others could also benefit from developing.

A lot of the documentation I write is aimed at a somewhat technical audience. They’re people setting up or using a web hosting service. Though I’m not writing for programmers per se, it’s not uncommon for me to include a code sample or instructions for using a programming-related thing (like installing a library or building a tool from source). Being able to read, understand, and write code samples myself, without the assistance of an SME, has enabled me to create more comprehensive documentation faster and with fewer hurdles. Like knowing a second (human) language, knowing the language of computers enables me to communicate with a wider audience. And it’s just a lot more fun to go out there and write something without having to ask for a developer to hold my hand.

Being able to program added depth to my work. Not only do I write the docs, but I can also write tools to help me produce better deliverables. For example, I wrote a collection of bash and Python scripts that reduce the process of generating and deploying my docs from a fourteen(!) step process to a one step process. Not only can I control of the words and screenshots in my docs, but I can also take ownership of the process surrounding the docs.

In short, being able to program has made me a better technical writer. It may or may not have any effect on my literal ability to write, but it has greatly expanded my capacity to produce documentation that people can use and learn from.

If you couldn’t already tell, this is definitely a skill I recommend to my fellow writers. Thanks to a bunch of really smart people, learning to program is easier than it has ever been at any point in computer history. As a matter of loyalty, I recommend taking up Python: it’s a popular, relatively easy-to-understand language (as compared to C or Java) and it runs on all major platforms. If you Google search for “learn python”, you’ll get a lot of resources to get you going, but here are some of my favorites:

  • The tutorial I started with some years ago, Instant Hacking, continues to be a fun, single-sitting introduction to computer programming with Python.
  • Try Python is an interactive, web-based tutorial. All you need to get started is a web browser and the Silverlight plugin.
  • Zed Shaw’s Learn Python the Hard Way is an opinionated, but effective Python tutorial thanks to some excellent exercises.
  • The Python website has an excellent list of Python resources for non-programmers.

Give programming a try. It won’t cost you anything (except a little bit of time) and I promise you won’t regret it.

Document your thoughts