Re: on the lack of documentation (was: Re: on neophytes vs perfectionists)

On 20 Dec 2008, at 02:04, Ed Stockly wrote:

This is one case (of many) where, between the sample scripts freely
available, the depth of the scripting implementation and the
appleScript community knowlege base, tons of detailed documentation is
not needed. [...]

Sorry Ed, but you really are defending the indefensible here.

I wasn't really defending anything. I was pointing out that this particular application actually has decent samples available, and is well supported by the community.

You said: "tons of detailed documentation is not needed" and told the user to go figure it out for themselves.

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. This is something that every other set of API documentation I've encountered manages to do. Without such essential basic details, users are left to figure out the valid combinations through trial and error and raking

Had the new sdef format introduced in 10.3 been thought out properly, it could have addressed this problem. It's simple enough really: just include a separate command definition for each acceptable combination of key parameters. Each of those definitions can then adequately describe exactly what each of those parameters should be, and what the particular effect of using them together will be.

For example, Finder's 'make' command would need, at minimum, one definition that describes how to make windows, and another that describes how to make files and folders.

make v : Make a new element

make -- Make a new alias file, document file, or folder

new : alias file/document file/folder -- the class of the new element

at : a reference to a container object -- the location at which to insert the element

[to : a reference to a container object] -- when creating an alias file, the original item to create an alias

[with properties record] : the initial values for the properties of the element

--> a reference to an alias file/document file/folder object : the new object

make -- Make a new Finder window or information window

new : Finder window/information window -- the class of the new element

[to : a reference to a container object] : when creating a Finder window, the target of the window

[with properties record] : the initial values for the properties of the element

--> a reference to a Finder window/information window object : the new object

Readers who are familiar with Dylan or other multiple-dispatch based languages will immediately recognise this pattern, btw, because it's basically nicked from there; c.f. multi-methods. Note that I don't suggest putting command definitions under individual class definitions as the Cocoa docs do as that would demand that Apple event IPC and the AEOM behave according to single-dispatch rules, which they don't. (Cocoa Scripting seems to assume a single-dispatch model, btw, which may be one of the reasons why scripting interfaces in Cocoa applications always feel a bit clumsy and contrived when compared to the best Carbon ones.)

Obviously, this sort of more detailed format would require application developers to spend more time writing their sdef, but as this is the bare minimum of information they'd be providing for any other sort of API anyway. Besides, with this 'multi-command' style of layout, it would be easy to 'inherit' command definitions from one another so that parameters that are always the same only need to be typed once for them to appear in each definition. Regardless of exactly how much extra work it would take, a bit more time spent by application developers would result in far more time saved by application users.

I don't know for sure why the heck Apple didn't design sdefs this way when they had such a golden opportunity to correct all of the mistakes of the old aete format. Perhaps the deficiencies of the scheme they did plump for simply didn't occur to them (how much eating of their own dogfood do Apple's application engineers do anyway?). Perhaps they thought that requiring developers to write more documentation than before would be received with hostility. Perhaps they thought that the sight of these expanded dictionaries would scare away users after all the marketing spiel they've been fed about AppleScript's 'simplicity' [1][2].

I was also making the point that there is a difference between the very basic language/technology support and support for scripting a specific application. I believed I was answering a question that indicated a blurring of that distinction.

That "blurring" is one of the direct causes of many of the problems that AppleScript learners face. Again, you're excusing something that deserves strong and repeated criticism, not to mention as much un-blurring as possible.

(The make verb is present in nearly all scriptable apps and functions in similar ways in most.)

References:
	>Re: on the lack of documentation (was: Re: on neophytes vs perfectionists) (From: has <email@hidden>)
	>Re: on the lack of documentation (was: Re: on neophytes vs perfectionists) (From: Ed Stockly <email@hidden>)