Re: Jargon Lovin' Fool

[Emily Berk <emily -at- armadillosoft -dot- com>]

These days, determining the appropriate vocabulary level is a real challenge.  
For example, I am documenting a J2EE tool targeted at experienced Java, but not experienced J2EE, developers.  The people I work with (extremely experienced J2EE developers) always start their applications server from the Unix or Windows command line.  

We didn't realize, until beta, that nearly every one else who tested the software, novice through J2EE hacker, launched their application server from the GUI.  

I observed one of the hacker types run through our beta test.  When he got to the line I originally wrote about how to launch the app server ("To launch the application server, type XXX in the command window."), he said to me, "Well, I'm going to launch this the way I always do, because I know it will call the startup file you just had me edit."  But then, when the procedure did not work (there was a bug), the guy re-tried the procedure exactly the way I documented it.  It still didn't work because the bug was still there; he was right, the startup file was called either way.

One of the (admittedly pretty novice) Java programmers I observed said, "I don't launch my application server that way.  What do I do now?"

So, what I'm trying to get at, is that:

1. Audiences contain multitudes -- it may be very hard to know your audience;
2. Even hackers sometimes do things the "easy way"; if a process is documented clearly, they can figure out what has to be done and what they can do differently;
3. Less experienced users will have much more difficulty unless coddled, so if you are opting for the jargon, you will have to add more words.  

Hacker way (with barely enough information for the novice to maybe catch on):
1.  Click on the Start button.  
2.  Select Run.  
3.  Enter command.com<ENTER> in the text box.  
4.  In the command window that opens, change to the applicationServer directory by typing:
         cd \appServer\<ENTER>
5.  Launch the application server by typing:
         XXX
on the command line.

GUI way:
Launch your application server by double-clicking the ApplicationServer icon.

The hacker knows how to avoid the GUI way if he or she wants to; the novice has a much more difficult time figuring out what you're talking about when you try to talk up to them (and think of all those electrons you are using to explain all this).

Just my (very recent) experience.

--Emily

On Fri, 19 Oct 2001 16:03:11 -0400, Ed -dot- Hawco -at- acecomm -dot- com opined:
>... That last one is the tricky one.My opinion is that with a mixed readership you are better off talking up to the lay readers and providing the
>wherewithall to learn (i.e., a glossary) than talking down to the technical
>readers and possibly loosing credibility.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~                            Emily Berk                                 ~
On the web at www.armadillosoft.com *** Armadillo Associates, Inc.      ~ 
~             Project management, developer relations and               ~
extremely-technical technical documentation that developers find useful.~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Announcing new options for IPCC 01, October 24-27 in Santa Fe,
New Mexico: attend the entire event or select a single day.  
For details and online registration, visit http://ieeepcs.org/2001

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.