From: peterk@cbmger.de.so.commodore.com (Dr Peter Kittel Germany)
Newsgroups: comp.sys.amiga.misc
Subject: Re: Commodity question
Date: 12 Jan 93 09:17:46 GMT
Reply-To: peterk@cbmger.de.so.commodore.com (Dr Peter Kittel Germany)
Organization: Commodore Germany

In article <crystal.725771527@glia> crystal@glia.biostr.washington.edu (Crystal) writes:
>In <10372@cbmger.de.so.commodore.com> peterk@cbmger.de.so.commodore.com (Dr Peter Kittel Germany) writes:
>>In article <crystal.724659529@glia> crystal@glia.biostr.washington.edu (Crystal) writes:
>> >In <rschuler.724653094@pv0221.vincent.iastate.edu> rschuler@iastate.edu (Rodney A Schuler) writes:
>> >
>> >>RTFM (read the FINE manual)
>> >
>> >Uh, if I may interject here... ?
>> >
>> >Many times I've found that the manuals written by *programmers* are difficult
>> >for the non-programmers/casual users to decipher.  
>
>>Sorry, wrong in this case. All the Amiga user manuals are *not* written
>>by the programmers but by docs specialists.
>
>If you read my post carefully you would see that I said  "MANY TIMES" not ALL
>the time...  

Yes, and I didn't want to say you were lying, but to give an information
how it's done at Commodore and that at least *this* issue is not a first
reason to be concerned.

>And just because something is written by a "specialist" does not AUTOMATICALLY
>mean that any fool/idiot can understand it.  

Yes, of course. Nobody's perfect.

>I don't know what kind of Dr. you are, Sir, but if you have ever tried to
>teach, you may have noticed that there are some students that you have to 
>clobber with bricks and TOTAL simplicity to get them to understand even the 
>most simple concepts, that to you are second nature/common knowledge.

Again you are completely right. I studied Physics and during my time at uni
one of my main tasks was to teach pharmaceuts (sp?) some physics. You can't
imagine less physics-motivated people than these. And yes, we had to do it
like for the extreme dumb ones.

But with computer manuals, there's a dilemma, we sit between a whole number
of chairs:
- If we do manuals for the dumb ones, the more literate users complain,
  what this company has an imagination of its users, they feel really
  blamed.
- If we do manuals for the literate ones, the others complain about not
  understandable docs.
- If we do both, the docs get so much volume that a) Commodore bosses
  complain about the cost, b) all (:-) users complain because they can't
  find anything in these mountains of paper.
- Some people like lengthy and wordy explanations. When we do this, the
  others complain about too much redundance and bloating.
- Some people like compact, short and precise information. When we do
  this, the others complain about lack of "explanation".

So my conclusion is that it's perfectly impossible to create documentation
that satisfies *every* user. They are sooo different. But of course we 
*try* to satisfy as many as possible. This is a case of nonlinear 
optimization and you never know where the optimum really is. But I can 
assure you that we listen to our customers and try to fix recognized 
deficiencies, once spotted.

>(BTW, I have trouble understanding the docs that came with the 2.04 ROM. I keep
>getting the impression that I need to have some sort of "background" which I
>don't have, in order to make sense out of the terminology used.  It doesn't seem
>to match the terminology I am used to from MAC/MS-DOS/APPLE ][ and CP/M. Like,
>what the H*ll is a "commodity"???  

Don't ask me. We even had no word for translating this into German. So for
us, this is simply a name of a drawer holding a certain type of service
programs. In English it's thought as something comfortable, if I read my
dictionary correctly... (I'm german, you know)

>...nor can I understand the difference between a utility, a tool or
>a project... *whimper*)

Well, a project is data, not program code (but OTOH, program source files
for an interpreter or compiler are also considered as projects), or better
"not directly excutable code". The differences between "tools", "utilities",
"commodities" or things in the System drawer are indeed not very big.
For Commodities, you can state that they are all handlers inserted into
the input data stream, doing some interesting and nice things there. They
are defined by their use.

-- 
Best regards, Dr. Peter Kittel  // E-Mail to \\  Only my personal opinions...
Commodore Frankfurt, Germany  \X/ {uunet|pyramid|rutgers}!cbmvax!cbmger!peterk
Wer's nicht kann, soll's bleiben klopfen oder Steine lassen!
Newsgroups: comp.sys.amiga.misc