Re: Is there an "official" term for this process?

Subject: Re: Is there an "official" term for this process?
From: John Posada <jposada01 -at- yahoo -dot- com>
To: Brian Martin <martin -at- sodalia -dot- it>, TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 17 Dec 1999 16:54:39 -0800 (PST)

> I saw the following two replies and feel compelled
> to add my nasty
> dispostion to the mix of opinions about what to call

And if I have a matrix describing characteristics of a
set of functions that may only have room for 3 or 4
words in each cell, I may simply be looking for a
short title of the function that I can place in a cell
of the matrix. It will have a one-line footnote giving
just enough information to describe the function and
that foot note will refer them to the section with
indepth detail. However, at the point of introducing
the term, I don't need the term to describe how or
what it does. That will be described in greater detail
somewhere else in the document.

> This next one is a worse solution because it forces
> users to learn the
> developer's jargon and doesn't tell then what the
> field actually does.
>
OTOH, the following description is WAY too long, gives
more information than is needed to convey its use, and
spends WAY too much effort describing how to enter a
letter and not enough information telling the user
what requirement it will fulfill:

> Click in this field and type one or more
> numbers or letters
> (small or capital). The items in the list that
> follow are
> filtered out accordingly. For example, if you
> type "C" only
> items beginning with capital letter C will
> appear in the list
> (such as CLLI01234456). If you type "c" only
> items beginning
> with small letter c will appear in the list
> (but not
> CLLI0123456. By emptying the field all the
> items in the list
> reappear.
>
> In conclusion, if you are developing an API guide, I
> recommend telling
> the developer users the name of widgets as they use

I'm not

> them. If it's an end
> user manual for the guy on the street, don't use

It isn't

Sometimes someone produces documentation that doesn't
fit in the narrow parameters of past experience. A
different purpose may require a different approach.


=====
John Posada, Merck Research Laboratories
Sr Technical Writer, WinHelp and html
(work) john_posada -at- merck -dot- com - 732-594-0873
(pers) jposada01 -at- yahoo -dot- com - 732-291-7811
"When in trouble, when in doubt, run in circles, scream and shout."
__________________________________________________
Do You Yahoo!?
Thousands of Stores. Millions of Products. All in one place.
Yahoo! Shopping: http://shopping.yahoo.com




Previous by Author: Is there an "official" term for this process?
Next by Author: Re: Is there an "official" term for this process? Summary
Previous by Thread: RE: Is there an "official" term for this process?
Next by Thread: To share, or not to share?


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


Sponsored Ads