Re: Jargon Lovin' Fool

Subject: Re: Jargon Lovin' Fool
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 24 Oct 2001 22:52:24 -0700 (PDT)


> > Huh? So, people can remain ignorant and still be smart?

> Yes. Andrew, I know plenty of intelligent people who neither know nor
> care about the networking technologies you document. They are ignorant
> about *your* area of expertise, just as--in many cases--you are
> ignorant about *their* area of expertise. This does not make them
> morons and you a genius. Technology is not the only worthwhile pursuit
> in the world, nor is it something everyone needs to master.

Christine, this isn't about *MY* area of expertise. Its about the level of
information you give readers. This can be applied to everything from
enzyme inhibitors (whatever that might be) to DHCP servers.

This is also not a "I am a genius, you are a moron" issue. Let's not turn
this into personal attacks.

Technology might not be the only worthwhile pursuit in the world, but that
isn't the issue here. The issue is...while documenting technology, what is
the appropriate level of information to provide the user.

> There are people who need all the knowledge you can impart to them.
> There are other people--many other people--who just want to do their
> jobs and will never, ever, ever need to know what DHCP is. They're the
> ones I write for.

Then you have made a choice. A choice to hide details from readers. That
choice has implications. One of those implications is that more savvy
readers will be turned off. If you and your company are okay with this and
it will be okay for the majority of your readers - then happy days. We are
in agreement. Love is in the air.

But, don't mislead yourself or your employer...less information is less.
You're explicitly saying "we are going to leave out some information
because we don't deem it necessary for our readers."

Savvy readers will be turned off by this. Some of those readers may have a
great deal of influence over your company's products. Therefore, any
decision to "dumb down" information must be carefully evaluated to assess
the risks. Just because John Q. User wants it ultra simple, doesn't mean
it is necessarily the best way to give it to him. Simplification may lead
to John Q. User not understanding the bigger picture. When a problem
arises, and they always do, John Q. User won't have any resources
available to him, because the documentation wasn't designed to deliver
anything more than the most basic information. This leads to support calls
and things like "these docs are useless!"

A good writer will take the time to evaluate his/her audience, the topic,
the details involved, and make a decision about how much information to
impart on the reader. Unfortunately, some writers make decisions based on
imperfect knowledge or information. Therefore, the outcome is less than
stellar. They assume they know their audience, when in fact they have
never met, spoke, or dealt with the people reading their material.
Moreover, these same writers are not users of the products, which makes
them even less qualified to make assumptions about the reader.

Therefore, the corrolary to this issue is that if you are going to "dumb
down" documentation, your are in a sense increasing your "technical
knowledge responsibility factor." In other words, if you are going to
distill knowledge, you need a complete image of the "original" information
to distill it correctly.

Another way to say that is: If you write for audiences that don't want
details, then you have a responsibility to that audience to be extremely
well versed in the technology being used so that you are empowered to make
accurate evaluations of the information you're distilling.

Moreover, there are plenty of geeks out there that want the details.
What's more is that geeks read docs, and they will spot attempts to gloss
over details as proof that you and your company are not qualified to be
making/selling whatever it is you're selling.

So before you gloss over all the details, consider the options, weigh the
issues, make a decision, and write the docs.

Andrew Plato

Do You Yahoo!?
Make a great connection at Yahoo! Personals.

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: Re: Layoff logistics and etiquette
Next by Author: Re: "They don't need no stinkin' documentation..."
Previous by Thread: Re: Jargon Lovin' Fool
Next by Thread: Word Trick: Detecting Hidden Graphics and Revealing Graphics Fil e Sizes

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

Sponsored Ads