Displays, defaults & values

One of my prime responsibilities as a technical writer is to edit into usability (and eventually post online in HTML) several dozen user manuals that were written by employees of the previous owners of the "legacy" software suite now owned by my current company. These manuals have already gone through a preliminary conversion process to extract them from a CD-ROM-based version that uses something called a DynaText Browser (sort of a proto-Microsoft Help), as well as a preliminary content edit by one or another of our programmers/analysts to account for changes to the software since the last CD-ROM update (which was quite a while ago).

You might think that wouldn't leave much for me to do. You would be wrong. Programmers and analysts are the last people who should be writing or editing documentation for end users. Not only do they litter the docs with jargon, bad grammar, and stilted language derived from programming requirements or specs, they can't even punctuate.

For example, whoever did that edit on the manual I'm currently working on seems to have been suffering from "Eats, shoots & leaves" syndrome¹, aka a surfeit of random commas. Mind you, the original (which I have in its entirety for comparison) was not wanting for extraneous commas to begin with. Nevertheless, these evidently weren't enough for our editor, who blithely inserted additional ones wherever, apparently, they took a breath while editing.

One of the most egregious -- and confusing -- examples of these respiratory commas was the following:

You use function numbers to control access to those functions you want only specific employees to perform.... Functions, which do not require control, do not need function numbers.

OK, let me get this straight: Function numbers control access to functions, which do not require control, so they don't need function numbers. Huh? FinallyI got the bright idea to check the original. Sure enough, it was supposed to read "Functions which do not require control do not need function numbers." So functions which do require control do need function numbers.

Other examples were not so much confusing as they were simply wrong:

"Function and user records must be coordinated to make sure that staff, have full access to the appropriate functions."

"Select the department whose, device list you want to copy."

As for the bad grammar and stilted language, nothing gets my editorial dander up more than the use of "display" as an intransitive verb. If I had a quarter for every instance of "Screen X displays" or "The password does not display on the screen" that I have changed to "Screen X is displayed" or "The password is not displayed on the screen", I'd be able to play the slots in Vegas through a very long losing streak.

In a similar vein, we have "default" used as an intransitive verb, as "This value is defaulted into the field." (This is a compound offense by virtue of using an awkward, and totally unnecessary, passive voice.) Now, "default" is a perfectly good intransitive verb, but that's in the context of defaulting on a loan or failing to complete a contest. If you're talking about automatically assigned settings or values, it's a noun or maybe an adjective, as "This value is the default for the field" or "This is the default value for the field."

And speaking of "value", another construction I see in our documentation that grates on me is, "You should value this field with an appropriate code...". I don't know about you, but I don't hold a database field in high regard or estimate its worth.

It's even entirely possible for more than one of these pet peeves of mine to appear in the same sentence. In fact, I ran across this prime example this very morning (I swear I am not making this up!):

"The record for entity 17, displays with the existing information defaulting into the fields on the editor screen."

Excuse me while, I go bang my head against the, wall.

¹Although you might not place a book about punctuation high on your list of must-reads, I highly recommend "Eats, Shoots & Leaves" by Lynne Truss. The title refers to a murderous panda. If that doesn't make any sense, well, read the book.