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.

Dude, it’s obvious

It’s so obvious. He lives in a pineapple under the sea. A pineapple. He’s not tough or brave or mean. He’s obviously promoting the homosexual agenda of, um, being nice to people and wearing ugly pants. Or something.

Every once in awhile we hear “such and such icon of childhood is destroying our youth,” followed by “young adults between 18 and 25 are moving back in with their parents and can’t hold jobs.” And people buy it every time. Next thing you know, people will be shocked by the way teenagers are dancing, and by the fact that people have sexual intercourse. After that, we’ll notice poverty or cults, or a new drug– my guess is betel nut or toads.

All Consuming!

I’ve got some shirts on order from Threadless, which is also in charge of OMG Clothing (slogan-oriented t-shirts). Then I remembered Preshrunk.info, the t-shirt blog. And there, I came across things like 80s tees — which also inclues an anti-80s section with a shirt that says “Retro Sucks” in a big fat retro font. My personal favorite right now is Sharp as Toast with its Propaganda Panda. Or maybe Tiny Factory, which has some great designs and funny political things too. I had to restrain myself– but I am now sure that my t-shirt idea from a year or so back was brilliant, and if I had only followed through, I would have a very expensive and time-consuming hobby on my hands.

Frizzante?

This is a serious resource on housing markets and the potential for a market bubble. I mean, I post the occasional link, but this is like, several essays and newsfeeds and what else who knows.

Links to: The Fed plays down a house-bubble, and on the other hand mortgage requests are down. Most notable, the ever-gloomy Stephen Roach points out that the US savings rate is approximately zero, and that “if it feels like a bubble, acts like a bubble, and looks like a bubble…”

I just like the feeling that someone is going to get hurt. I think it’s what drives people to tune in to American Idol.

Stoopid

The conspiracy theorists in the tax-denial movement remind me a lot of the right winger nutters, like, say, Phillys Shclafly (did I spell that right?) who was opposed to the equal rights amendment because paying fair wages to women would cause communism. Or something like that. Her logic wasn’t clear but it had something to do with free day-care for young children being socialist, unlike free education for kids over six, which is to be expected.

Anyway, “The Hearts of Men” told me a lot about what economic policy should be to achieve fair and just wages for women, and explained that the early-20th-century ideals of the “family wage” and the male breadwinner are basically gone, or at the very least can’t be relied on as instruments of social policy any more (if they ever were reliable). But it didn’t tell me anything about the nature of committed relationships or how to keep a man or anything like that.

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.