TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Amy Probst will be <<...writing "Job Aids" for users of a new
enterprise-wide financial management system this university has adopted.
Basically, it's all about acronyms, codes, and procedures that seem to
exist only for self-importance, at least from the user perspective. My
audience is comprised of data entry and secretarial staff, many of whom
possess limited language and analytic abilities.>>
I don't have any samples to give you, since my audience is exclusively
educated experts in a specific field, but I can suggest that you're unlikely
to find examples that precisely match your current situation. That being the
case:
<<[I] feel especially protective of my users; they are so often left feeling
stupid at the hands of some manual or instruction that is simply beyond
their level of vocabulary or comprehension.>>
It would make an awful lot of sense for you to spend some time talking to
them and finding out the kind of work they need to do and what they find
hardest to do. That gives you a breakdown of what you must document: their
daily tasks, with an emphasis on the most difficult ones (which is where you
get the biggest payback). Once you've got that list, you need to sit down
with them and talk to them again to see the kinds of words they use to
describe these tasks. That gives you the rudiments of a "translation table"
that lets you map their vocabulary to the vocabulary used by the geeks who
wrote the software. For example, I'll bet you that what the geeks call
"accounts payable" and "accounts receivable", the users call "bills and
cheques". That's not to say you shouldn't use the geekspeak, but rather that
you should provide it as a supplement to instructions written in their own
words (tell them about "paying bills", but make sure they know this is
"accounts payable" on the screen). Next, sit down with them and figure out
what their typical work styles are; two obvious possibilities are that (as
you noted) they simply can't handle accounting buzzwords and need (as I
suggested) translations, but it's also possible that they're a low-literacy
bunch who require special job aids (e.g., graphics rather than long passages
of text, simple words, restricted vocabularies). The only way you'll know
what works will be to talk to them and find out, then test what you produce
to be sure you've understood their needs.
Oh yeah... don't forget to do some 'before and after' tests to demonstrate
the value of this work to your bosses. For example, time users filling in
the details in a difficult screen now, and again after your documentation is
in use. Figure out the time savings, add it up across the organisation, and
point out with a smug grin that you recovered your development time
(including all that schmoozing) in less than 6 months. That impresses bosses
muchly, and gives you a lot stronger bargaining position when it comes to
suggesting future projects (e.g., refining the interface based on the
problems you observe among the users).
"Technical writing... requires understanding the audience, understanding
what activities the user wants to accomplish, and translating the often
idiosyncratic and unplanned design into something that appears to make
sense."--Donald Norman, The Invisible Computer
