Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)
Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)
- Subject: Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)
- From: Ed Stockly <email@hidden>
- Date: Fri, 26 Dec 2008 12:59:16 -0800
You said: "tons of detailed documentation is not needed"
Which is exactly what I believe.
Ed, I don't care what you believe, only what logic and evidence you
can provide for your assertions. Which you've not.
I would say you have expressed your *opinion* that much much more
documentation is needed. I expressed my opinion that while more may be
needed, not nearly as much as you believe. And I did support my
opinion with logic and reasoning.
>>has>>A full description of the parameters that each command can
accept isn't an optional extra like a tutorial or FAQ - it's
absolutely vital information that should be in every single
application's core documentation. It's not sufficient only to know the
names of each class and command, you also need to know all the valid
ways in which they may be combined.
A requirement for developers to make the commitment to support each
command with that level of documentation is not realistic, reasonable
or necessary, and may cause some developers to give up on the
technology.
I also pointed out that the detail of documentation for each command
that you advocated would be overly redundant for commands like "make"
and would make dictionaries huge and less useful, but that it may be
possible to automate something similar to that level of documentation
as Scripter did in OS7-9.
I originally wrote a long, detailed response to this post, but as it
mostly just rehashed stuff you've already ignored I won't bother
posting it. However, I will pick out the following as it's just too
rich to pass up:
(That was my approach as well)
Just to clarify for the list, Make is not a command. It's a verb.
Semantic word games. The reason 'verb' and 'noun' get used in
introductory AppleScript is because these terms are already familiar
concepts to non-programmers, whereas 'command' and 'object' have to
be taught first.
For non-programmers, describing commands as verbs and nouns makes
sense. It's the English-like metaphor. That's how I learned, that's
how it has been described in AppleScript books and articles. Using
commonly understood terms makes it more clear to non-programmers
without the need to teach programming. "make" by itself does nothing.
It can be thought of as a verb that needs a noun. Programmers and
more experienced scripters generally get that it's a simplified, less
technical description of the technology.
A command consists of a verb and an object.
Jargon's jargon and can be made to mean almost anything if you want
it to, but here's the ASLG's definition:
"A command is a word or a series of words used in AppleScript
statements to request an action. Every command is directed at a
target, which is the object that responds to the command."
A command is a *request* and is directed *at* an object. Even ASLG
disagrees with your interpretation.
The verb/noun metaphor expresses the same concept, but is less
technical and uses words that do not need further definition, perfect
as an introduction to the concept for non-programmers.
If you're going to "clarify" things for the rest of us, please try
to know what you're talking about first.
I wouldn't presume to clarify things for you, but for the non-
programmers on the list who have been following the thread.
ES
_______________________________________________
Do not post admin requests to the list. They will be ignored.
AppleScript-Users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
Archives: http://lists.apple.com/archives/applescript-users
This email sent to email@hidden