Re[2]: More personable tech writing

[Bonni Graham <Bonni_Graham_at_Enfin-SD -at- RELAY -dot- PROTEON -dot- COM>]

     Len writes:
You have to know your audience *really, really* well to get away with
this for a series of books! My own geiger counter goes off of the scale
anytime *I* see jargon of *any* kind in technical prose. I tend to skip
familiar sections entirely. But maybe folks like me aren't in your
audience. You better make sure!
***end of original message

Yes, but.  When I was working for a library automation firm, the biggest
complaint about my first set of manuals was that I didn't use ENOUGH
jargon.  My users felt like I didn't know what I was talking about when
they saw "plain language" phrases for jargon terms.  It made them
suspect the _rest_ of my information!  So in my next set, I used library
jargon liberally, but had our system designer (a Master of Library
Sciences) check it over carefully, and augment where she felt necessary.

     SO, I'd say more that if you're going to use jargon, be sure you have
     a typical audience member in house who can examine it for you
     (something we have here at Easel, since we write for programmers,
     mostly).  We also, to address another of Len's concerns, have a very
     multicultural staff (members from Denmark, Thailand, Germany, the UK,
     etc.).  Not all these people are on-site, but almost all of them are
     on the review list.

     To tie back in to my "overcoming technophobia" posting, when naive
     users seem some jargon they are familiar with in technical prose, it
     makes the rest of it look less intimidating.  I stand by that -- the
     best you can ever do is write to MOST of your users, anyway. (Who was
     it who said you can't please all of the people all of the time?)

     OTOH, I'd never user jargon in the manual set I'm writing now -- for a
     report and analysis tool for end users.  They come from several
     different industries -- I'm having a hard time coming up with examples
     generic enough, but yet also real-world.  So, as usual, _it depends on
     your audience_!

Bonni Graham                               |
Technical Writer                           | serif, n.  A teensy-weensy
Easel Corporation, ENFIN Technology Lab    | crossbar attached to the
Bonni_Graham_at_Enfin-SD -at- relay -dot- proteon -dot- com | ends of letterforms by
President, San Diego STC                   | malevolent typesetters.  Ac-
                                           | cording to popular legend,
NOTE: apparently my email address needs    | the first serif was designed
to be typed exactly as it appears here,    | at Nottingham.
punctuation and all, or the system gets    |
upset.                                     |          --Ezra Shapiro