cellio | Entries tagged with writing

Some judges on the state supreme court are upset because one of their colleagues wrote an opinion in verse. They object that it's unprofessional, etc.

I have very different objection: judges who write opinions in verse shouldn't write bad verse! Check this out:

A groom must expect matrimonial pandemonium
when his spouse finds he's given her a cubic zirconium
instead of a diamond in her engagement band,
the one he said was worth twenty-one grand.

"Our deceiver would claim that when his bride relied
on his claim of value, she was not justified
for she should have appraised it; and surely she could have
but the question is whether a bride-to-be would have.
-- Justice Michael J. Eakin

Update: I think writing in verse is cool in the abstract; I just twitched at this particular instance.

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. )

I'm reviewing some documentation I wrote back when I first joined this company, to see if it's still accurate. I encountered the following statement (in a situation where A logically must be greater than B):

"[class] does no checking of these two values; if you set [A] to be less than [B], the results are undefined."

What I really want to write instead is: "if..., you will deserve what you get, and don't call us for support".

But that would be unprofessional. Shucks. :-)

Current Mood: mischievous

Monica

silly judges

What makes an excellent programming writer?

oh, the temptation

Expand Cut Tags

Syndicate