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.

( So, Monica, tell us what you really think. )

for the DDR crowd

Pump-it-up dreams

As you might conclude from the above, the choir crowd went to Dave & Busters last night instead of Gullifty's. The food was decent. There aren't that many places that can satisfy all our constraints: serves food after 10, not smoky or noisy, and provides options for a vegetarian and someone (else) who's lactose-intolerant. This seemed to work, though I didn't look closely at the meat options to see if there were sufficient non-dairy ones among them.

After we ate, Chris demonstrated Pump It Up and got Gail to play one round with him. It looks like it would be fun; maybe next time I'll try it. Or maybe I'll try to sneak over to Chris' or Deanna's house, ask the occupant to set up the game and then leave, and try it out in private. :-) (At my current level of exposure, Pump It Up and DDR are basically interchangable.)

the pledge

I objected to the pledge of allegiance from a fairly early age. Or rather, I objected to being required to say it every day in school. I had problems with "under God", but more importantly to me at that time, I had problems making that kind of commitment. I remember asking how a 10-year-old could be expected to make such an open-ended promise. I got told to just do it.

Some teachers (and maybe my parents?) told me to just cover my heart with my hand and stand there silently. This was dishonest, though; I didn't think I should be giving the impression that I was saying it when I wasn't. But mostly that's what I did, because I wasn't aggressive enough to really push the matter. I valued my grades and I was told they would suffer if I made a big deal out of this.

So I don't really buy the argument that no one is forced to say it so it's not coercive. Of course it's coercive; many things done in the name of public education are. This doesn't mean it's automatically wrong; there are areas where I not only accept but expect coercion in school, such as to instill minimum standards for interpersonal interactions. But I think it's silly to say that the pledge isn't coercive when it often is.

I do object to this particular coercion, though. And beyond the general objection, I have a problem with "under God" being included in anything that's required (or nearly required). It's not just the pledge, either; I'm uncomfortable when being "sworn in" (I say "affirm") as a juror ("...so help you God"), and I was startled when I was asked to swear an oath ("...before Almighty God") when applying for a marriage license. All of these are inappropriate, and all of them are functionally if not technically coercive.

I am not an athiest. I believe in God. And the God I believe in shouldn't be trivialized in this way. The hordes of school children who say these words every day do not, for the most part, have any real understanding of what they're saying. If that's not taking God in vain, I don't know what is.

And it is not for the state to give some religious views precedence over others. This isn't a constitutional argument; that only restricts Congress. This is a moral, or perhaps ethical, objection. No one has a pipeline to The One Truth here; what is right for me is not right for you, and what is right for you is not right for me. This does not change if you get yourself appointed as school superintendant, or governor, or president. (In this case, you don't even have the weight of historic precedent; "under God" is a MacCarthyism, not original text, and I gather that the author of the original would be displeased if he were capable of rendering an opinion.)

From what I understand of the court ruling (not being a lawyer or scholar), the ruling is goofy in one way: they seem to have said that this particular text is forbidden in the abstract. Forbidding "under God" in an arbitrary piece of text is as offensive as requiring it; the problem, either way, is in how the text is used. The judge who said that there's a problem with the athiest's kid even hearing "under God" is way out in left field, assuming he hasn't been quoted out of context. What they should have done is to forbid schools and the government from requiring anyone to take this pledge as it is currently written, and left it at that.

One of these days maybe I'll get around to school prayer. :-)