Yeah? Well, release this!
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
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
posted by Lance Manion at 6:04 PM
4 Comments:
I agree with Mr. AnonymousPants. This is an excellent blog!
43 liters is a lot of Diet Coke, but it could be worse. It could be Diet Pepsi. Ick.
I don't know where I was going with this... My bad, yo.
Nice to see the EMVP's are the same no matter which corner of the country you call home (for instance, the cover of the manual for the software I help develop has a picture of a woman using a mac on it. My program doesn't even run on a mac!).
Thanks to your introductory internet course on Release Notes Composition, I feel I will be able to better explain all the wonderful features, and timely bug-fixes now available. Not to mention that there is the add-on utiltiy to cure genital warts.
I have broken with the coursework on one crucial matter though, instead of 43 liters of Diet Coke consuption daily, I find that a mixture of 5 liters black coffee between 8 and 11, then 38 liters of Mtn. Dew from 11 - 6 works better for me. Of course I do use the optional quart of everclear and/or bacardi 151 per hour to enhance performance.
"I just bang the words together, you know?"
Deep love to you for that line.
Also, I know I asked for the stories, but the pictures? They might make me die.
Post a Comment
<< Home