Poor Imposture

I realized this week that the main thing wrong with the world is that it matters more whether you can get the job than whether you can actually do the job. It's such a pain to hire or fire someone, that as long as a person isn't waving a gun around and threatening to shoot someone, it's easier just to say "Eh, maybe he'll get better, and the next one could be worse" than it is to find someone else. (If a person actually is waving a gun around, that's probably not the right time to fire him either...)

Anyhow, I spent a large portion of the last week revising documentation for the product I've been working on for the past two years. Apparently we paid some vendor to write user guides less than a year ago, but things have been changed in the past six months. Since we've been pretty bad at documenting what changed, I'm pretty much the only person who really can update the user guide.

We've already established that I like to make fun of other people's spelling and grammar, but I went into this whole thing thinking "hey, it was written by a professional -- all I'll need to do is change the sections where we've changed the product."

Then I read the existing guide.

Here's a condensed version of what the hundreds of pages of professionally-produced user guides look like:

Table of Contents

Scope

Flow of Control

Task 1

Task 2

Task 3

Task 4

End

Scope

This user guide is meant to be used by the users.

Flow of Control

(Diagram that was superseded two years ago here.)

Task 1

The first task is done by the RF Engineer when they enter a Date and then click on the Submit button. Then you're done until you get to Task 2.

Task 2

After the first task, Task 2 should be done by the Regulatory user. They need to click on the approve button.

And on it goes. Seriously, if you write technical documentation for a living, shouldn't it just be second nature to format everything the same way? If you're going to capitalize and underline the button names, then capitalize and underline all of the button names. And we aren't speaking German, so random nouns shouldn't be capitalized, no matter how important you think they are. And I know there isn't a good gender-neutral pronoun, but one RF engineer is not a "they". That's just wrong. Also, if I'm the one who has to go through and figure out how to fix all of the MS Word styles in the document so the table of contents doesn't look like it was done by a schizophrenic, something is wrong.

Sometimes you just want to demand your money back.