Apple

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"

Which is exactly what I believe. If a dictionary is well written (iTunes is probably a 7 on a scale from 1 to 10, so there is room for improvement) and if there are sample scripts available (there are for iTunes, and I agree it would be better if more were provided by Apple) then tons of documentation is not needed for an *experienced* scripter.

told the user to go figure it out for themselves.

Never said that, not even close. I was trying to answer a question about how the "make" command worked and simply mentioned that once the user has mastered that in one application it would apply to numerous applications. That is one of the things that makes AppleScript AppleScript.

What I believe happens is that when experienced programmers come to AppleScript they expect it to be simpler than every other language they've used and expect to be able to apply their knowledge without having to learn how the technology works, and that is not the case.

That is, I believe, why many programmers struggle with applescript, and the verb/object construct is one of the first concepts that throws them.

>>>>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. In addition, if you master scripting one single scriptable application you can take that knowledge to script almost any scriptable app.

That's not to say that there some application do not have sample scripts available or a community knowlege base. I was referring simply to the case of iTunes. If you want to master appleScript that's a good app to start with.

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.

I think Shane and Mark had something to say about man pages for shell scripts in that regard. Let me just point out that I believe that the kind of documentation your discussing (including samples) is needed for shell scripting.

Let me also point out that in some applications a full list of all the objects and parameters the "make" verb could act on would be larger than the app's current dictionary. To apply that standard to every verb and every command would be unreasonable.

In the OS 9 days Scripter had a command builder that would automate exactly that. I'd like to see that for OS X.

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.

This is where we disagree about documentation. I believe a well written dictionary (FInder: 6 out of 10) is all that's needed for an experienced appleScripter.

Once you've learned how "make" works (in Itunes or Pages or iPhoto or Finder) you can apply that to any app.

make <something> at <somewhere> with <properties>

The kind of detailed documentation you're advocating is overkill. I makes an assumption that anyone looking at any dictionary is an appleScript novice and needs to learn how to do the most basic commands on every app.

I don't believe that level of documentation is needed, nor do I believe that it's reasonable or practical to expect developers to provide that level of documentation.

What I suggest instead is that dictionaries be well written (see Script Debugger 9 of 10) and that the developer (or the community) provide a well organized collection of sample scripts.

Given the state of the technology and the level of developer support I think that is far more reasonable, realistic, useful and practical.

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.

I wasn't making an excuse, I was simply trying to help.

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

"Similar" != "same". And without documentation, there is no way for a user to know if two 'make' commands will behave the same, or only similarly; and, if the latter, what those differences are. This is buck-passing, pure and simple: by application developers, by you.

Just to clarify for the list, Make is not a command. It's a verb. A command consists of a verb and an object.

In other languages the command might be makefolder or makewindow or mkwnd or mkfldr

In appleScript the command is 'make a new folder' or 'make a new window'. And, of course, making a folder requires different parameters than making a window. But in all but a few exceptions the make verb functions the same way across thousands of applications. (I can't think of any exceptions)

Application developers - and, by extension, Apple, who are meant to provide developers will the tools and guidance they require - are already bad enough at delivering poorly designed, abysmally documented scripting interfaces, whether through laziness or (most likely) honest ignorance of what's required. Please don't encourage it by downplaying the pain this causes or pretending the problem doesn't exist, or else they'll never learn and great swathes of potential converts will continue to loathe and reject the platform.