Blog: July 2002

Most of these posts were originally posted somewhere else and link to the originals. While this blog is not set up for comments, the original locations generally are, and I welcome comments there. Sorry for the inconvenience.

What makes an excellent programming writer?

Yesterday someone called me for a reference check on a past coworker. After she'd asked me lots of detailed questions about this person's skill, technical knowledge, work style, and so on, she asked: "is [name] a superstar, or just very very good?". Ok, that's kind of a bizarre question, I think. I mean, it just begs for a definition of terms -- and, in fact, after I gave my answer, she asked me what I thought the key features are in a superstar. I gave her a few main points and this seemed to satisfy her, but I found myself thinking about it after the phone call was over.

I am a technical writer. Specifically, I write documentation for programmers. Most technical writers write documentation for end users, so "programming writers" are already kind of rare. (I know; I've tried to hire 'em. :-) ) And, within the set of people who claim this specialty, there are ones who "get it" and ones who don't. Ego aside, I think I'm personally an excellent programming writer, but it took me a while to get there. I have had the pleasure of working with a few other excellent programming writers over the years (including the subject of the phone call). So here are some of my thoughts on what makes a superior writer of this sort. Some of these apply to technical writers in general, but I'm really talking about the sub-species here.

An excellent programming writer:

  • knows how to program, which is different from knowing a programming language. The C course you took at the local university will come in handy, but you also need to have first-hand knowledge of what programmers do and what they need from your documentation. You need to understand abstract programming concepts that transcend specific languages. You need to understand how software is designed (which, ideally, happens before much production code is written). If you are still in college, find your school's "fundamental structures" class (usually about the second course in a CS track) and take it. It won't give you everything you need, but it'll give you the essential basics.

  • knows, or can easily learn, key software-design concepts. Phrases such as the following should not be completely foreign to you: threading, deadlock, atomicity, design patterns, runtime exception, call by reference (and call by value), and function/method/operator overload. There will be others depending on language and technology domain. You don't have to know it all at the start of the job, but you have to be able to absorb it and truly understand it, not just echo it back.

  • is conversant in the relevant programming language(s). You don't have to be able to write amazingly clever code or anything like that, but you ought to be able to write "hello world" and you ought to understand the constructs that pertain to that language well enough to learn your particular product. For example, in Java, do you understand the differences between classes and interfaces? In C++, do you understand what virtual methods are and how they affect inheritance? In languages that use them, do you understand how pointers work? Do you know why multiple inheritance makes people twitch and why GOTOs are considered harmful?

  • can read a function/method signature. You need to know what facts are obvious from the signature and which ones need to be documented, and you need to be able to evaluate the plausibility of existing documentation that you come across, because sometimes code changes and the documentation doesn't. If the signature says the method returns an integer and the description says it returns a number, do you know whether that is correct? If the Java class returns a Collection, does that tell you everything you need to know? If the JavaScript function takes an Object as a parameter, is that clear enough?

  • instinctively asks questions like "what happens if I pass a negative number for 'quantity' here?" and "what happens if the index exceeds the length of the array?" and "when can this return null?" and "what exceptions can this throw?" and "what happens if the passed output file can't be written?". In a lot of ways, you and the QA folks have a lot in common.

  • knows how to just read the source code to answer questions like those I just gave.

  • takes questions like the previous ones up a level. It's not just about understanding this class or that interface or those functions; you have to understand how they fit together and why the programmers provided this interface instead of some plausible alternatives. You should routinely think of questions in the space of "what would happen if we did it this way instead?". You should think of some of the same alternatives that the programmers did. (Occasionally, you might think of ones they didn't and that might work better. Be prepared to contribute to software design!)

  • writes precisely. It's not just about grammar and knowing whether "anal-retentive" has a hyphen. A misplaced "only" can completely change the meaning of the sentence, and phrases like "is an error" and "override" and "set" and "unspecified" have precise meanings. You should be the sort of person who automatically pays attention to such details.

  • is a user advocate. You are the first "external eyes" on the product; how usable is it? Remember, the question is how usable it is by programmers, but not the ones on your team.

I may add to this list later, but this is a good start.