Where Liz Links: BAD!

January 29, 2003

BAD!

So, for work right now, I'm creating a Help file for a system I've never used before, primarily by picking apart its user manual.

Whoever wrote the user manual was... Less than professional. Since I've been raving about it for about the last three hours, I thought I'd share some tidbits.

(Stuff in [square brackets] is where I replaced potentially identifying and proprietary names of things with harmless substitutes. It shouldn't affect the overall feel.)

I'll even include - for those of you unused to the way professional technical documents should look - my re-writes.

If the [device] was written successfully, the user needs to be aware that the data written to the tag have been sent to the designated [data-collection] server as well.

If the [device] was successfully updated, the data will have also been sent to the [data-collection] server.

The System Administrator will configure the settings for this function; however, the user needs to be aware that if the files being written to [devices] are not making it to the designated server, then there is a backup FtpPutFile Control Service on the [software] that will attempt to resend the file within the next 24 hours.

The System Administrator will configure the settings for this function. If the designated server does not receive the files, the backup FtpPutFile Control Service on the [software] will attempt to resend the file within 24 hours.

This screen looks similar to the screen used to create the [collection] record; however, there are some small differences between the two screens.

This screen is similar to the [Creation] screen, but functions differently.

Notice that this screen has as a down arrow next to the [ID] field. This is important. The user cannot create a new [collection] record from this screen.

The user can not create a new [collection] record from this screen. The user should select an already-created [ID] by clicking on the down arrow.

The most important feature to note about the Detailed Info screen is that it will display the [ID] of the [collection] that the selected line item belongs to.

The Detailed Info screen will display the [ID] of the [collection] to which the selected line item belongs.

The manual is full of "the user must be aware" and "it is important to note that" and "blah blah blah; however, yadda yadda yadda"s. I'm ready to tear my hair out. If the user didn't have to be aware of something, then it wouldn't be in the manual! If it wasn't important, then it wouldn't be in the manual! And fully 95% of the "however"s can be replaced with a period.

It's probably a good thing I don't know who wrote this. I'd be tempted to tell them what I think.

Posted by Liz at 02:56 PM

And then they said...

GACK!!!

Good thing, indeed. I'd be tempted to beat them with the hick'ry stick they *should* have gotten in elementary school.

Posted by: Gris (email) on January 29, 2003 06:19 PM

Heh. Your story came in handy at my Internet Orientation last night, Liz. I had one nice, older lady who was helplessly confused by the alphabet soup she got thrown into when she started reading about the internet-- URL, HTTP, ISP, .com, .edu, .etc... so she asked me what they meant, and I expanded each of them for her, and then explained what they were in plain English. And she said, "Well... why couldn't they just say "web address" in the first place? So I calmly explained that the language of the internet was written by techie geeks, and she went away much happier. ^_^

Posted by: Gris (email) on February 5, 2003 12:55 PM