Workpersonship

["D. Margulis" <ampersandvirgule -at- WORLDNET -dot- ATT -dot- NET>]

<indignation>Today I watched two system architects--make that two very
bright system architects (estimated median IQ of 150)--struggle through
the directions for using a feature of some software they had just
installed.

The software in question helps track software requirements and it comes
from a well-known, highly regarded provider of development tools.

I asked to see a copy of what they were having so much trouble with, and
I have that copy in front of me now. The instructions, which are posted
on a support page on the company's website, do not match the help text
that ships with the software. I presume that the help text is in error
and that the technical note on the website is a correction, although it
does not say so.

The most charitable thing I can say about the page is that the
disclaimer at the bottom is the clearest text on the page. It says (in
all caps, which I will refrain from duplicating here), "Information
provided in this document and any software that may accompany this
document (collectively referred to as a Technical Note) is provided 'as
is' without warranty of any kind, either expressed or implied..."

Good thing!

The instructions themselves are full of typos, punctuation and spelling
errors, inconsistencies in person, instructions out of sequence,
inconsistent usage of typographic styles, inconsistent use of numbering,
and a general lack of organization. I'm not picking nits here. Anyone
can have a senior moment and get an apostrophe or a comma wrong. And
yes, sometimes the proofreader misses it, too, if you're lucky enough to
have a proofreader. What I'm looking at is simply unintelligible as a
procedural instruction, regardless of reading level or your opinion on
the importance of following the conventional rules of orthography,
punctuation, and style.

Harrumph!

I would not presume to suggest that any sort of credential automatically
qualifies a person as a tech writer. For all I know the writer of this
tripe has a Master's degree and is an officer of an STC chapter. (Then
again, maybe the tech writer was out sick that day and the page was put
up by a developer.) But something has to change if we're going to
engender a warmer reception when we first walk up to a developer and
say, "Hi, I'm a tech writer, and I'm here to help."</indignation>

Dick Margulis