Right now my project is to write a set of release notes. You'd think that was pretty easy. Just write down what's new and what doesn't quite work right. Unfortunately, the Marketing department believes that my document has the magical power to make things go away. So we have conversations like this.
Evil Marketing VP "I see that we can't display reports in Japanese"
LM "Nope."
EMVP "Can you take that note out?"
LM "Sure. But it's going to be a nasty surprise to the Japanese."
EMVP "I see. Yeah, let's take that note out."
LM "You do understand that taking the note out doesn't actually change anything. The reports still won't display in Japanese."
EMVP "I understand that. It's a matter of perception."
So apparently we'd like to give the Japanese the perception that we don't actually test the product. My whacky belief that this might be a bad thing is probably why I make the small bucks.
So for those of you who'd someday like to join the hallowed ranks of the professional technical writer, here's the Lance Manion guide to writing release notes:
There are three types of notes, Broke Things, Things that used to be Broke, and New things that will probably get Broke. In the notes we call them Known Issues, Resolved Issues, and Enhancements.
Let's start from the bottom, shall we?
Enhancements - You want this to be the longest section, so you grab everything you can think of. Is the background a different color? Great! Interface updated for increased readability. Or something. If all else fails, make features up. I'm personally responsible for a set of process control software out in the world that cures herpes. It's not like anybody reads this stuff.
Resolved Issues - These are easy. Generally you're writing something to the effect of "The application is now compatible with 7200 RPM hard drives." What this really means is "Your computer will no longer make a hideous screeching noise before setting your hard drive on fire and shooting it out the window."
Known Issues - These are the toughest to write (or, as hackers would say, These are t3h Suxx0R") What you have to do here is describe everything that doesn't work in the product. Now some people might ask "But Lance, if it doesn't work, why are we releasing the product at all?" Beats the hell out of me. I just bang the words together, you know? Here you write things like "In rare cases, the archiving stored procedure may corrupt the user ID tables. Be sure to backup your database nightly." What this means is this "If you so much as look at the server crosseyed, it's replacing all of your most valuable data with porn."
And in an enterprise level application, you'll have to document about 150 of these bad boys. In a day. And people wonder why I drink 43 liters of Diet Coke a day.
Coming tomorrow "Dougie and the Mixed Nuts part 2 - Provocative Photos!"
LM