Lack of documentation

Question

In regards to finding ExtendScript APIs and documentation,
none of them has a complete reference and only anecdotal examples.
Specifically, I'm updating a solution written for InDesign CS2 and
have found it is now broken with InDesign CS3. This is a chronicle of
my efforts to find documentation thus far and a complaint to Adobe:
BAD SOURCE
0. Adobe.com -> Search -> ExtendScript
I got a Flash tutorial, robohelp tutorial, etc. What I did NOT get
is a centralized center for scripting Adobe applications. ExtendScript
can be used on nearly all Adobe products, but you'd never know that's
what the name is or its breadth.
GOOD SOURCE - (yet not complete):
1. Extendscript Tookit 2 ->Help->Adobe InDesign CS3 Object Model
Seriously, you put it under Help ... Help is where I should look for this?
That's about as intuitive as putting the gas pedal in the glove box. It's the
closest thing I could find to a full API reference but I suspect it's incomplete
and why is it not in an indexable HTML format on Adobe's site anywhere?
BAD SOURCE
2. http://www.adobe.com/devnet/
Not 1 mention of ExtendScript. This is the technology as a name.
It's not called InDesign Script. It's called EXTENDSCRIPT. No illustrious
articles, videos, blogs. And it puzzles me why the InDesign Server Resources
site links to this dead end but the same link on regular InDesign goes to the next one:
GOOD SOURCE
3. http://www.adobe.com/devnet/indesign/
Finally, we're getting somewhere. You'll find this:
http://www.adobe.com/devnet/indesign/documentation.html
What you'll see here are pretty useful PDFs, I'll admit. With some good
use cases fleshed out. There are even ZIPs with sample code in it.
The inherent problem is that there is not an example for EVERY use case
and EVERY possible scenario.
What is missing from this page (and Adobe's entire web presence) is a
full Reference (see #1). For those who haven't experienced the bliss of a full
instructions manual, it would be akin to this:
WHAT WOULD BE NICE:
http://livedocs.adobe.com/flex/3/langref/
InDesign CS2 had a full reference guide. It disappeared with CS3 and CS4.
As a developer, this is beyond frustrating. I wouldn't ask a mechanic to fix
my car without a complete manual for repair. It shouldn't be a maze to hunt
and peck around for this information.

Answer 1

Hi steveo,
re: "It disappeared with CS3 and CS4."
No, it didn't. It just moved into the object model viewer in the ExtendScript Toolkit. All of the content from the previous PDF reference manuals was folded into the information provided there. At the same time, by not publishing the reference PDF, we were able to significantly increase the number of examples (which now make up the bulk of the Scripting Guide).
re: "The inherent problem is that there is not an example for EVERY use case
and EVERY possible scenario."
Look at the size of the InDesign model. Consider that most objects can be nested almost infinitely (a text frame can hold a character which can contain a group, which can contain another text frame, etc.). There is just no way that we can provide an example for every possible scenario.
I agree that the documentation and examples are too hard to find. But the InDesign scripting home page (which is listed in most of the sample scripts that get installed with InDesign) is at:
http://www.adobe.com/products/indesign/scripting/index.html
You'll need to click the Scripting Resources tab once you get there. I don't know why.
That said, there's little specifically for InDesign CS2 there (it's been awhile since CS2 was released, but if it were up to me, the content would still be there). Most of the CS4 scripts will work with CS2, one notable exception being the find/change scripts.
re: "What is missing from this page (and Adobe's entire web presence) is a
full Reference (see #1). For those who haven't experienced the bliss of a full
instructions manual, it would be akin to this."
Agreed, that would be great.
The PDFs in the ESTK folder, by the way, are accessible from the Help menu in the ESTK.
Thanks,
Ole