Expectations for UXP API Documentation

[ericdrobinson]

As a UXP Developer, I expect the UXP API documentation to provide the following:

• An overview of the environment, including JavaScript VM details (e.g. "V8 version 8.4").
• An overview of UXP architecture, including:
  • Core JavaScript APIs - APIs that exist thanks to the core language support (provided by default by the VM).
  • UXP Core APIs - APIs that Adobe implements within all UXP environments. These should be versioned.
  • Host APIs - APIs that are unique to each Host Application.
  • I expect to see sections for XD and Photoshop on the same UXP documentation site.
• An overview of the differences and similarities between JavaScript for UXP environments and JavaScript for Web and NodeJS environments.
  • UXP was designed with some portability in mind. Explaining where APIs are expected to act identically and where they are simply convenient syntactical emulation is important.
• A clear and easy to navigate API hierarchy.
  • I should be able to quickly filter down through the API hierarchy to find useful intra-linked documentation. The NodeJS docs are a decent example. The XD documentation is another decent variation.

With that said, the current the JavaScript Reference documentation provides zero insight as to what JavaScript environment is available in UXP. The only two sub-items ("Global Members" and "Modules") feature completely different sub-hierarchies and seem to organize content into semi-logical groupings. That is certainly one way to organize APIs but it is not terribly discoverable. I would much prefer to see things broken out by the "Core JavaScript APIs", "UXP Core APIs", and "Host APIs" categories that I described above. Where UXP Core "global" APIs are concerned, I would expect things to be broken out by the "object" to which they are attached. Specifically this means window or document. I would hesitate to call these "globals" and refer to them otherwise as perhaps "built-ins" or the like. If window works the same way in UXP as it does on the Web, say that explicitly. Example:

"As with JavaScript on the web, UXP environments have a global window object that features many useful (and possibly familiar!) APIs. When using APIs available on the window object, you can optionally remove the window. object as UXP will look on the window object for the item in question if it doesn't exist in the local scope."

The more that you can clearly state which APIs come from the core JavaScript language, which come from your base "UXP" environment, and which come from Host applications, the better.

Honestly, I would prefer that you guys quit it with this "host application specific documentation site" stuff and unify. I understand that presently each host application dev team gets to somewhat cherry-pick what they want out of UXP core, which makes it difficult to do that unification, but providing a "UXP Documentation" site that had one section for JavaScript API docs, another section for UXP API docs, and a set of sections for Host Application API docs, would dramatically improve my life as a Creative Cloud UXP developer. I would suggest that each of those three sub-sections of the overall "UXP API Reference" also be versioned and that they be intra-linked. Photoshop 2021 runs on UXP 4.1? Cool. I can set my "documentation view" to that version of Photoshop and it will show me the UXP docs related to UXP 4.1.

I really do not want to have to relearn a new documentation setup for every UXP-enabled CC application.

---

I understand that it's still early days for the documentation, so my hope is that the above helps provide you with what at least one person in your audience expects out of the effort that you put into building the docs.

[ericdrobinson]

This may already be in the works but the documentation for the Photoshop API is vastly superior to that of UXP APIs.

The Photoshop API documentation is readable and searchable. The UXP API documentation hides 95% of the information behind foldouts which entirely inhibits searchability and scanability.

Please do not do this.

[kerrishotts]

@ericdrobinson Please split this into two issues, if you wouldn't mind. :-)

[ericdrobinson]

@kerrishotts At what boundary, specifically? Do you mean my initial post and the comment? I.e. that I should make the comment its own separate issue?

[kerrishotts]

@ericdrobinson Never mind; figured out how GH can split for us. The accordion issue is moved to #106.