Recombee AI destination docs

[gezgblack]

Proposed changes

These are the destination docs for Recombee AI.

I've disabled the settings section from being pulled in from Partner Portal because it lacks a lot of details that the team at Recombee wanted to add including the use of markup. I've added their elaborate Settings section at the bottom of this doc, the same way the usual Settings section gets added.

Please do not merge yet. I will add the updated destinations.yml file merge by myself once approved.

Merge timing

Not urgent yet.

[netlify]

✔️ Deploy Preview for segment-docs ready!

🔨 Explore the source changes: c8de4ab

🔍 Inspect the deploy log: https://app.netlify.com/sites/segment-docs/deploys/60dafa233f4a000007127b87

😎 Browse the preview: https://deploy-preview-1674--segment-docs.netlify.app

[sanscontext]

@gezgblack I have a bunch of edits, sorry this seems like a lot. I appreciate how thorough the partner team is being here. :)

Question about the Settings fields - the fields we import from the Partner Portal/ConfigAPI are in markdown. The reason we pull them in is because for many destinations they're quite detailed, so I'd consider actually putting this text into those fields if possible. Happy to discuss in case I'm missing a good reason to split them out here. :)

[gezgblack]

@gezgblack I have a bunch of edits, sorry this seems like a lot. I appreciate how thorough the partner team is being here. :)

Question about the Settings fields - the fields we import from the Partner Portal/ConfigAPI are in markdown. The reason we pull them in is because for many destinations they're quite detailed, so I'd consider actually putting this text into those fields if possible. Happy to discuss in case I'm missing a good reason to split them out here. :)

Hey @sanscontext, the confusion about the settings had arisen because the settings section that the customer fills out in their Developer Center doesn't seem like it includes markdown. Here's a look at what that settings section looks like for the partners:

As you can see, the description field looks basic and from their experimentations, didn't support markdown.

You mentioned that Partner-Portal that we have access to supports markdown. Here's the issue that I see. This is their Partner-Portal settings section: https://app.segment.com/partner-portal/integration/recombee-ai/settings. The data that you see there like the "description" property shows up in the destination settings when they try to set up the destination. I feel like if we put all of that settings description into their Partner Portal settings it will look cluttered in the destination settings. The other question is, should I manually enter those long additional settings into their Partner-Portal instance? Should I add them on top of their existing descriptions or remove their current descriptions from Partner-Portal and override them with the long list?

[sanscontext]

Hey @gezgblack if you look at the settings for, for example Braze, or Adobe Analytics, their settings descriptions do have markdown included. If this option isn't showing up correctly in the Partner Portal that's maybe a question for whoever is currently maintaining that interface? I'm not sure who that'd be though 🤔

Stylistically, while we'd like the descriptions to be shorter and less-cluttered, prior art is to put as much context as needed into the description for the sake of the user. Given that all the docs research I've ever seen says that people will do anything they can to not navigate away from a page to look at docs, I think this is still our best option. Happy to have a discussion with you and whoever else?

[gezgblack]

Hey @gezgblack if you look at the settings for, for example Braze, or Adobe Analytics, their settings descriptions do have markdown included. If this option isn't showing up correctly in the Partner Portal that's maybe a question for whoever is currently maintaining that interface? I'm not sure who that'd be though 🤔

Stylistically, while we'd like the descriptions to be shorter and less-cluttered, prior art is to put as much context as needed into the description for the sake of the user. Given that all the docs research I've ever seen says that people will do anything they can to not navigate away from a page to look at docs, I think this is still our best option. Happy to have a discussion with you and whoever else?

The issue is that the markdown is not available in the Developer Center Settings Builder. It looks like it is available in the Partner Portal. The partner doesn't have access to the Partner Portal, they only have access to the Developer Center Settings Builder. With that in mind, should I manually copy-paste their setting into their Partner Portal settings section?

[sanscontext]

Oh wow! I didn't realize we were maintaining two different UIs for this. Let's discuss this on the channel so I don't miss anything - there might have been a good reason for them not to allow markdown.

[gezgblack]

I believe this one should be good to go now @sanscontext. Take a look and let me know if you're happy enough with this.

⚠️⚠️⚠️ Please don't merge, just looking for approval ⚠️⚠️⚠️

I'll merge myself once I add the updated destinations.yml file.

[sanscontext]

Hey @gezgblack let me reformat the settings just a bit, and then I'll approve. :)

[sanscontext]

Approved! Thanks so much for your patience with the settings stuff! Merge when you're ready. :)