Devdocs: Add Adobe Stock Integration setup documentation

[filmaj]

New topic request

Description

In early 2020, the Adobe Stock Integration extension project (https://github.com/magento/adobe-stock-integration) will be released and become available for use. This integration will add a new sub-section to the standard Media Gallery, wherein admins can choose to 'Search Adobe Stock' when selecting an image from the media gallery.

It would be good to add a section to the devdocs on how to install the integration. We should add a new subsection under Setup > Magento Extensions Guide.

Content checklist

• [ ] The Magento Extensions Guide should include a left subsection for Adobe Stock Integration, with an Install subsection that links to...
• [ ] ... a topic that provides steps for installing the Adobe Stock Integration, and should be based on the existing Installation Guide.

Additional information/resources

The project's existing wiki has a lot of relevant info, like the Installation Guide. As a new Magento user/developer, I was able to follow this guide to set up a working instance of the project on my own local instance, so I think this would be an excellent starting point. There are also many other wiki articles containing information about the project overview and design.

There is also a public instance with the integration installed and enabled: https://adobe-stock-integration-eeen5iy-rnacvccre3346.eu-4.magentosite.cloud/admin/ (user:admin, password:123123q). To see the integration in action, log in as admin, select Catalog -> Categories -> Content -> Select from Gallery -> Search Adobe Stock.

Finally, we have a project in progress on the merchdocs repo where the more merchant / user-facing documentation will be developed: https://github.com/magento/merchdocs/projects/6.

I would love some feedback on how to structure this, or really, any guidance or suggestions at all anyone can give. I am happy to draft a pull request for these changes but would appreciate a bit of guidance; perhaps a template on if other projects / integrations have provided this before?

[jeff-matthews]

HI @filmaj! Thanks for opening an issue and providing a great detailed description of the need.

A new Functional Areas subsection sounds like a good idea.

@keharper (from the Magento Docs Team) will assist you with drafting a PR (or multiple PRs depending on how much content we need to add).

[filmaj]

Thanks for your quick response @jeff-matthews!

One area of confusion for me is where the system configuration information for the extension should go. @leslietilling suggested in her merchdocs plan/overview for the Adobe Stock Integration project (https://github.com/magento/merchdocs/issues/77) to add a new section to the advanced system configuration screen (I've filed this here: https://github.com/magento/merchdocs/issues/89). If it is preferable to have the setup documentation in the user-facing docs, then I am not sure if it makes sense to have that information in the devdocs. So then the question becomes: what, if anything, should be showcased in the devdocs? Perhaps only the installation of the extension into a Magento instance?

I have many questions as I'm still pretty new 'round these parts so I appreciate any suggestions or insights and thank you all in advance for the hand-holding 😊

[jeff-matthews]

You're asking great questions!

This could get long, so please bear with me.

Context

Your questions are actually forcing us to confront some inconsistencies on the devdocs site.

For example, the following existing devdocs topics contain both install _and_ config steps for extensions:

• https://devdocs.magento.com/extensions/amazon-sales/
• https://devdocs.magento.com/extensions/b2b/
• https://devdocs.magento.com/extensions/google-shopping-ads/

However, the following devdocs topic includes install steps only and then links to merchdocs for config steps:

• https://devdocs.magento.com/guides/v2.3/security/google-recaptcha.html

What we want to do and why

I can see the benefit of including both install _and_ config steps in one place, because it's likely that whoever installs an extension will also configure it and sending them to two places instead of one for the info they need to complete the integration is inconvenient.

However, that might be outweighed by the scenario of post-install config. For example, after an extension is installed, it's possible that a non-developer would need to adjust the config and therefore look in the merchdocs for guidance.

Based on that rationale, I think it makes more sense to split the config info (~devdocs~merchdocs) from the install info (devdocs).

What now

Since the Adobe Stock Integration installation requires CLI and server-level steps, that info should go on devdocs for sure.

The config info should go to merchdocs per https://github.com/magento/merchdocs/issues/89.

Instead of adding a new subsection to the Functional Areas section, I think we should add a new subsection under Setup > Magento Extensions Guide.

[filmaj]

That makes a lot of sense to me @jeff-matthews ! I've updated the original issue checklist to try to reflect your suggestions.

[keharper]

@filmaj @jeff-matthews ASI needs to have an info architecture pretty similar to Inventory Management. There's too much going on here to for everything to live tidily in the Magento Extensions Guide. @sivaschenko confirmed that ASI is built in an extensible way, and so we'll need to include more architecture/interface/service contract info than I originally expected.

ASI should have its own section under Functional Areas, with topics in different places in the filesystem.

I propose devdocs ASI work be done in 3 phases:

1. ASI Overview and installation
   The conceptual topics would be placed in the guides/v2.3/adobe-stock directory, while the installation info would go under extensions. I'm not sure how important the OAuth 2.0 info is

2. REST integration
   Document the REST endpoints. I don't think having a tutorial would be all that valuable, but having additional info about creating custom filters and handling paging might be very important. I searched Adobe Stock for "puppies" and "blue" and received over 65k hits. How do you deal with all that?

3. Module extensibility
   Detailed architecture, interfaces/service contracts, do you need to do anything differently for Page Builder and the old WYSIWYG module?

[jeff-matthews]

Thanks for the additional insight @keharper. Agreed.

[filmaj]

Just adding some initial pointers based on @keharper's suggested outline and mapping to some of the project's wiki content:

1. Re: overview/installation, other than the Installation Guide, I'm not sure any of the other wiki articles could be gracefully lifted and dropped in as 'conceptual' guides. Perhaps the Implementation Guide, though it is a bit sparse and seems to me a bit incomplete. Perhaps the Adobe IMS OAuth authentication method overview article could be used as a basis for an authentication overview section? We may end up needing to write most of this from scratch... not sure.
2. Re: REST API, we could use the Web API article as a basis here, though I think each endpoint will require additional, more detailed description. Additionally, there are three deeper design documents available that describe the three major functional areas of ASI that we could either integrate into the API documentation or leave as separate articles: Image Search Design, Saving Image Preview Design and Licensing Image Design. Regarding creating custom filters, I think the Simple Filters section of the Image Search Design document could be used as a basis for educating users, though I defer to @sivaschenko! The above design documents also link to service and interface contracts, which leads me to the final point...
3. Module extensibility. The existing Modules wiki article looks pretty good and even has pretty pictures! @keharper do you think having a module overview belongs in this third section, or should rather go as part of point 1 above in the general/conceptual overview? We also have a Service Contracts and (internal) API article (that as I mentioned we could link to from the REST API where applicable).

Last point from me: we also have a Database Schema overview article. @keharper where do you envision this information would belong in terms of your outline (if any)?

Thanks for the guidance, we really appreciate the help!

[keharper]

To answer the easiest question first. We won't need to publish the DB schema info.

1. I realized that I made the mistake of reading what's been written, and not what needs to be written. The current installation docs describe how contributors can install ASI. This info should not be migrated. The installation docs should state how Open Source/Commerce customers install the module. My guess is the installation process would be very similar to Inventory Management. It's possible that this topic can't be written until the packaging is finalized.
   Location: extensions/adobe-stock/index.md
   Primary navigation path: Setup > Magento Extensions Guide > (left nav) Adobe Stock Integration > Install

   The overview topic can probably share a lot of content with the one for merchdocs. My first impression was that we have a good start on the wiki, but now I'm realizing the info is sparse, and that we can't re-use any of the existing diagrams. I would expect the topic to show the happy path of searching for images to licensing an image (steps 1 -5 under "Use cases" on the wiki front page.)
   Location: guides/v2.3/adobe-stock/index.md
   Primary navigation path: Functional Areas > Adobe Stock Integration

2. You've got a good handle on the issues here. The REST endpoint docs need to be expanded, but there's plenty of pages that can be used as a template, such as Manage Sources. If you keep the examples consistent with each other, you eliminate the need for a tutorial.

   The search/GET endpoint looks like it has a complicated payload, so that's why I thought it might be better to have a separate topic on tuning the query.
   Location: guides/v2.3/adobe-stock/_various_
   Primary navigation path: Functional Areas > Adobe Stock Integration > REST

3. I was thinking of having a separate architectural overview. Someone who found the page thanks to Google or our internal search can quickly determine if they're in the right place by scanning, without getting bogged down with architectural stuff. But ASI is fairly small, so two overviews might not be warranted. I'd make that call after writing the main overview.

   I'm not ready to think too hard beyond this.

[filmaj]

Thanks @keharper! I'll mull your guidance over and chat this through with @sivaschenko before taking a stab at a draft for the overview.

[filmaj]

So I might have jumped the gun on this issue... after last week's sprint to get initial testing packages ready for the integration, I became aware that actually the integration will be bundled with all editions of Magento2 starting with version 2.3.4.

So, in that sense, there won't be any installation needed at all, only configuration - which we are handling documenting over on the merchdocs repo.

Going to close this issue... sorry to take up everyone's time here! My bad.

[diazwatson]

Not at all, thanks for your hard work :)