How Can a Technical Writer Develop a Love of Programming Code?

by Tom Johnson on Apr 18, 2013
categories: technical-writing

Anne Gentle, one of my favorite bloggers, recently wrote about the diverse backgrounds of the technical writers around her — see Developers, Writers, and First Jobs. In her post, she included a job description for a "Microsoft Programming Writer." It's kind of a mind-blowing description. Here's what Microsoft is apparently looking for:

You are comfortable creating both code and prose. You have a passion for the web and its ability to solve real world needs and create connections between people. You know that there are many technologies that fuel the web, and you're like a kid in a candy store when you play with new APIs and discover how they expand your abilities. Your real satisfaction comes when you successfully teach someone else how to use those APIs, though, through a blog post or talking at a meetup. You've got a knack for coding: you use patterns and practices such as responsive design, you know your way around jQuery and Modernizr, but you prefer to code in adopted standards. In fact, you occasionally read W3C specifications for inspiration. Maybe you hope to someday edit specs… (See Microsoft Programming Writer I job)

Anne indicated that she is heading in the direction of developer documentation.

I really liked her post. It begins somewhat subtle and then steers right into one of the most challenging questions for a technical writer: How do you become a technical writer who loves code?

As I wrote about in Four Types of Technical Writers Companies Are Looking For, the need for API technical writers is a growing trend, especially in the Silicon Valley area. If you have experience documenting APIs, which usually entails knowing at least one programming language, you have a lot more jobs to choose from.

The problem is that most technical writers love to write words more than write code. We love “language” -- but usually we say this referring only to the English language.

In reality, program code is a language, and learning it isn't too unlike the strain in learning another spoken language, like Arabic or Russian. Symbols, syntax, structure, and keywords all communicate meaning. Why is it that technical writers, especially with a humanities background, might consider themselves lovers of language but fail to see programming code as yet another language worthy of study?

Like Anne, I'm also trying to steer in the direction of developer documentation. Not only does it lead to more career opportunities, it's also content users need. Interfaces are becoming more intuitive, users more tech savvy. The day when you needed to document how a graphical user interface works is waning. Or I should say, the need can be more easily be filled by a technical writer of average skills.

But APIs require another skill set entirely.  Nothing is immediately intuitive. Understanding how the API works involves knowing how programming works, and specifically the rules of a particular programming language.

With some study and effort, you can learn a programming language, no matter how right-brained you think you might be. See this post on Quora about learning hard subjects. The Quora author explains:

I start from this premise: if there's a concept that many people have learned in the past, anyone of average intelligence is capable of learning it if they follow certain procedures and if they're able to remove certain roadblocks.

This means that you have to start by giving up the (surprisingly comforting) idea that "I'm just one of those people who don't get it." How often have you heard that? "I'm just one of those people who don't get technology." "I'm just one of those people who don't get Shakespeare." "I'm just one of those people who don't get Math." Etc.

The truth is that you're one of those people who has tried and failed to get whatever subject you attempted to master. That's demoralizing, but it doesn't mean you're incapable of getting it. It just means that you tried and failed. The benefit of claiming "I'm just one of those people" is that it lets you off the hook. To move forward, you have to refuse to let yourself off the hook.

In other words, don't give up after an hour of frustration when you don't immediately understand programming (or in the author's case, recursion in physics.)

The Quora advice is solid, but in my opinion, the question is not “can you learn it,” it's how can you love to learn it? That's the essence of the description Anne posted from the Microsoft writer -- someone who playfully experiments with APIs out of curiosity, learning how code works for the love of code. Not some who buckles down hard-scrabble and sees the task through with clenched fists.

I'm not entirely sure how you make the switch from Thomas Pynchon to Python, or from James Joyce to Java, or from Chaucer to C++, but at some point, I think the technical writer who lives and breathes code has to first develop a genuine interest in code. He or she has to see code as a beautiful language, one worthy of study, memorization, play, and delight.

I haven't reached that point. But I did catch a glimpse of it last week. I bought a personal subscription to Safari Books Online to have more than a dozen JavaScript how-to books at my disposal. At one point, while reading about how web architects tried to solve resource loading issues on web requests, I had an insight that maybe computer language wasn't just a confusing set of rules some techie made up late at night in his or her garage or basement. Maybe it was much more intelligent, something fascinating, maybe more advanced and complex than human language. Maybe computer language, the way it's collaboratively constructed, with variables and functions, contains efficiencies and logical constructs that are both revolutionary and profound – even more so than the English language.

That kind of perspective is somewhat fleeting as I read computer books, but I don't think any technical writer will be successful in developer documentation without first seeing computer language as a language and second seeing its beauty.