Category: Words

How not to write instructions

There are two lines of actual description in the esd (Enlightened Sound Daemon) manual page. I know this is not useful or constructive criticism– and I don’t know enough about how they’re supposed to work to begin to help with these documents. I just want to point out a bad example for you to avoid emulating as you go about your own development.

DESCRIPTION
esdcat pipes data from a pipe to the sound device

USAGE
esdcat [“-s” server] [“-n” name] [“-b”] [“-m”] [“-r” freq] < file

Let me count the ways this is bad. I’m not talking about how it should have an “OPTIONS” section where the options are described, although to fit standard manual page layout, it should. I’m talking about basic, basic failure to write anything at all useful to anyone other than the developers.

-s server: So, we’re specifying… the host or destination for our audio data?

-n name The name of the pipe? The name of the server? The audio device? The user?

-b and -m I think that -b and -m mean 8-bit and mono, because they’re used for that in other related applications. But the manual page doesn’t explain them here.

-r frequency Setting frequency with -r is strange– Maybe you meant -f? Or did you mean sample rate? Other esd-related commands use -r to set the sample rate. Maybe in this application it’s set in Hertz rather than bits per second. Or is it samples per millisecond? Or does it set the frequency of the sound you want to hear come out of the speakers, so you could put in audio recordings of a concert and have them come out as a single, even tone. Or you could increase or decrease the pitch by the frequency specified?

< file What kind of file? Is this the file used for output? Input? Probably a named pipe or a device of some sort, since esd doesn’t handle any audio file formats directly.

Esdctl and the rest of the esd docs are almost as vague.

Type Design Makes Good

Sure, we all hate Comic Sans. But this is a truly heart-warming story of typeface design where it really counts. Let us all give thanks for the typefaces and graphic designers in our lives.

No, really, I mean it.

Dammit, you don’t believe me when I say something sincere, do you?

OK, I think it’s funny. But it’s also really cool. It’s saving lives through graphic design. That’s really useful and good and beautiful.

Who knows what evil lurks in the hearts of men?

I’m reading Nickel and Dimed author Barbara Ehrenreich’s (and how hard is that name to spell, by the way?) book The Hearts of Men: American Dreams and the Flight from Commitment. So far she’s covered the expectations of men in the 40s and 50s (become the sole supporter of a wife and children; women’s work was not valued and wives were regarded as economic parasites; neither men nor women were very happy with this arrangement as we all know by now) and how the Beats rejected the “responsibility and maturity” required of men; and how the sixties counterculture rejected not only the “responsibility and maturity” model of masculinity but also masculinity itself, especially for its destructive, violent impulses.

So where is she going with this? I can’t tell. Does Barbara Ehrenreich know what evil lurks in my heart? And will reading her book help me understand my dreams and flight from commitment? I mean, I’m not a sole provider, I don’t have to support a family, and I’m not the only income in my household, but… I still fear the same sort of sacrifices the grey-flannel conformists of the fifties feared (and made anyway). What’s in my heart? Aside from fear and resentment and selfishness, I mean. And red blood cells. That doesn’t count. I wish I knew.

Meat in St. Louis

My sophomore year in college, my girlfriend at the time wrote a paper to the effect of “what’s the deal with gay men and Judy Garland?” This entailed, for the most part, watching Meet me In St. Louis repeatedly. I mean repeatedly. But I learned something from it: the way that Judy Garland represented, for a certain time, a certain barely repressed spirit to certain segments of the population.

And the original lyrics to the song “Have Yourself a Merry Little Christmas.” Places like Carols.org.uk describe it as the saddest Christmas song, but they totally miss the reason. They have the lyrics as

Through the years
We all will be together,
If the Fates allow
Hang a shining star upon the highest bough.
And have yourself A merry little Christmas now.

That is how it’s been popularized and is the more common version. But the line “Hang a shining star upon the highest bough” is totally out of place, because it’s been put in to make the song less sad. The original is “until then we’ll have to muddle through somehow.”

The song is about being separated for an indefinite amount of time from everyone and everything you love, and having to find what happiness you can now; it’s about everyone around you completely ignoring your emotional needs, about celebrating even though you’re desperately unhappy, and having to hide that unhappiness from everyone around you. That’s why it’s the saddest Christmas carol.

And the fact that Judy Garland got roles where she sang regretful torch songs covering that same sense of alienation was what made her so popular with legions of alienated people, gay and otherwise, through the forties and fifties. I have no idea what turned her into a gay icon.

But I do know that, ever since that fateful week, I’ve had the complete lyrics to all too many of those songs burned into my memory. Including the parodies, like Beat me In St. Louis.

Comments back on

Comments are now working on the blog. Chatter away. Today’s topic of discussion:

Telling children that Santa Claus, the Easter Bunny, etc. exist sets them up for an ultimately disappointing revelation that their parents have lied to them, and their universe is not as safe and comforting as they once believed. Some argue that children may come to the conclusion that their parents have lied to them about the existence of God as well.

If this is true, should parents:

  • Tell their kids that Santa exists, in order to teach them the hard lesson that adults are not to be trusted and God does not exist?
  • Not mention Santa or treat Santa as a fairy tale, assuming that the kids will learn eventually that adults are merely human in some other way.
  • Tell their kids that Santa exists, because it’s fucking hilarious to play that kind of trick on people, nobody but your own kids are gullible enough to fall for it.

Words and Phrases to Ban

Those of you prone to business-speak, those of you who need to talk about money and sales and markets, please pay attention.

If you are discussing, say, the size of the market for a particular category of software — PC games, for example — and it has increased, you know it is growth in the market. If it has not increased (as is the case with PC gaming, which appears to be losing out to consoles) you can describe that as “flat” or as “no growth” or as “not much growth at all.” If it goes down, like graphics software has, (apparently people are satisfied with what they have, and/or get it free with their cameras), for crying out loud, do not call it negative growth.

Now, I admit it’s not as easy as all that to figure out what to call it. You can’t call it a loss, because it isn’t: we’re talking about less money coming in, not money actually going out. Nor can you call it “shrinkage,” which is already reserved for theft of physical products somewhere between manufacture and consumer (that is, the sum of product lost to assembly-line workers taking a few home, boxes “falling off the truck,” and shoplifting). You can, however, call it a deterioration, decline, decrease, or a falling-off. Any of those is vastly preferable to the abomination that is “negative growth.”