Re: Jargon Lovin' Fool

[Bruce Byfield <bbyfield -at- axionet -dot- com>]

Andrew Plato wrote:

> Yes. I do. Because I can see through dumb little "friendlisms" and so can
> a lot of geeks. Its a waste of time. Just say boot and be done with it.
> Don't try to sugar coat the issue and make it nice.

Geeks are far more likely to criticize explanations that are so general that
they mislead or over-simplify. To be honest, when I'm writing for geeks, I'm far
more concerned with avoiding that kind of pitfall. It seems a far more
legitimate complaint than a choice between two word choices that are both
commonly used.

> > - Does anyone really believe that writing clearly automatically equates
> with
> > writing down to technical readers?
>
> I can - it depends on how you do it. A lot of writers overly wordsmith
> things and cause them to lose the original meaning.

No argument. In different circumstances, I've argued your position. But I see
the technical and writing sides of the job as two chainsaws that I'm juggling -
I have to balance both of them to do the job properly.

> You're probably right. Most techies wouldn't notice or care. But they may
> in other areas. "boot" vs. "start" is awfully simplistic. But if you spend
> an inordinate amount of energy polishing off all the edges in a document,
> you risk alienating more savvy audience members.

I suppose it depends on the length to which you're willing to go to simplify the
language. "Boot/start" isn't very important. But if you tried to avoid using
DHCP when explaining networking, you'd be going too far. The effort required to
avoid using DHCP would obviously be much greater than the effort required to
explain the concept, so you might as well go ahead and use the term. Besides, if
your audience is ever going to delve further into networking, they'll need to
know the term.

> Also - think of documentation as a sales tool. If the docs speak to geeks,
> it may impress them enough to recommend the technology. If the docs are
> polished nonsense, the geeks won't be impressed and you'll lose the sale.

Again, I think accuracy and completeness is what will impress the geeks.

> Agreed. But information can be dramatically "soiled" by over-wordsmithing
> and grammar nazis. You risk losing nuance and alienating more technically
> oriented readers. If you polish the hell out of every sentence, it may
> sound great to other writers - but the nerds behind the scenes won't go
> for it. It will turn them off.

Perhaps the principle could be: Simplify when possible, but not at the expense
of accuracy or completeness.

--
Bruce Byfield bbyfield -at- axionet -dot- com 604.421.7177

"In the ashes of American Jerusalem
The prophets live their deaths out on the corner
The pretty people say, 'There should have been a warning'
But nobody heard it."
- Rod Macdonald, "American Jerusalem"




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