Re: Standard Additions documentation
Re: Standard Additions documentation
- Subject: Re: Standard Additions documentation
- From: Paul Scott <email@hidden>
- Date: Sat, 20 Dec 2008 15:16:47 -0800
On Dec 20, 2008, at 1:58 AM, Chris Page wrote:
I suppose we should think about updating the Standard Additions
dictionary to pick up the revised reference documentation from the
ASLG, but I'm hesitant to attempt to fill dictionaries with more
than quick-reference information.
If we added links within the dictionary to the ASLG, would that
help? Would anybody notice and follow them? (Has anybody noticed and
followed the one for “do shell script”?)
Yes, links would be helpful.
The primary source should be a PDF document that I can download and
keep on my computer. There should be a dictionary link to this primary
source, and one or more additional links that point to technical notes
that arise out of questions garnered from customer experience, such as
this list.
I would like to see, in addition to the new (and yes, very much
improved) AppleScript Language Guide, these PDF documents:
Scripting Guide for Mail
Scripting Guide for Safari
Scripting Guide for QuickTime
Scripting Guide for Final Cut
Scripting Guide for Compressor
Scripting Guide for ...
Scripting Guide for Standard Additions
(Please, OP, don't flame me ... I promise you I won't engage in that
discussion under any circumstances)
In other words, a Scripting guide for each and every individual Apple
software product. I think there's enough to be said for any one
application to make a reasonably sized document without too much
repetition. Keep in mind that some repetition from document to
document isn't necessarily a bad idea. Having these guides will set an
excellent example for other vendors to follow.
Simple examples that clarify ambiguity are always a great idea. These
should be part of each guide, where appropriate. I'm not asking for a
library of examples, just one or more simple ones, as necessary, that
clarify vague references.
Furthermore, the AppleScript pages on the Apple Web Site need to be
greatly expanded, especially in the "Learn" sections, perhaps in a
format similar to what we see in the XCode documentation with HTML
pages and a link to a matching PDF document.
Keep in mind, that knowing the syntax of AppleScript (or any language)
is only a small part of learning the language -- one can learn C in an
hour, and spend years getting to know the run-time library. Similarly,
each scripted application has its own "world" of objects that behave
and interact in unique ways. If these are clearly and thoroughly
documented the script writer can be productive in much less time; and
with a reduced level of frustration will be much more likely to do a
lot more with AppleScript.
The "Guides" should not be considered "reference-only" documentation.
They should be organized in a way that makes them valuable both as a
reference and as a learning guide. To make AppleScript truly
"accessible" to everyone, this is what is required.
Maybe this seems daunting (and some will claim unnecessary -- they're
wrong), but like any daunting task, the sooner you begin the sooner it
will start to take form and ultimately get done.
Paul
Attachment:
smime.p7s
Description: S/MIME cryptographic signature
_______________________________________________
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