Re: Jargon Lovin' Fool

Subject: Re: Jargon Lovin' Fool
From: Emily Berk <emily -at- armadillosoft -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Sat, 20 Oct 2001 13:03:24 -0700

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<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:
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.


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 *** 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

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 for more resources and info.

Previous by Author: Terminology question: Deprecated function
Next by Author: PDFs on Unix
Previous by Thread: Re: Jargon Lovin' Fool
Next by Thread: Re: Jargon Lovin' Fool

What this post helpful? Share it with friends and colleagues:

Sponsored Ads