So this is the time of year when all Nice Jewish Boys (and Girls) should turn their minds to ethical questions. And no field is more fraught with ethical conundrums than… technical writing. For example: is it better to document every API method or option, no matter how obsolete or dangerous? (Otherwise known as the “Give them rope and explain how they can tie their own noose” approach.) Or should you try to hide all the bad stuff for the user’s own good? (Otherwise known as the “Allanon School of Technical Writing.”)

Usually I advocate the first school. Basically I figure that people are grownups, and if you do your best to explain things, hey, it’s their lookout. This is not to say some projects shouldn’t go the other way, but for the most part, I think more information is good. Plus, the first approach means more work to do, which theoretically means more employment for myself and my fellow tech writers! Solidarity, my brothers and sisters!

Anyway, while I do prefer the first school, this approach sometimes leads to amusing results. For example, my group maintains a certain internal tool that has a few dangerous command-line options. Most of these fall into the category of, “only use this if you really know what you’re doing,” which is fine. But there’s one that I had to document like this:

“[blah blah blah descriptive text.] CAUTION: Using this option can completely destroy your system. Do not use this option.”

I ran across this description again just a few days ago, and man, it never fails to crack me up. Trust me, we technical writers are really hilarious once you get to know us.