Make role connection metadata more clear

[shaydewael]

Description

See conversation in #5807

We should add some clarity around connection metadata + make associated types clear for the different types. This should probably happen on the Role Connection Metadata page, but may consider the user reference page where the endpoints are listed as well.

I think as part of this, we should consider where those endpoints exist—i.e. should they really be on the User resource page (since they require the OAuth scope), or should they be on the Role Connections page since that's where the rest of the associated info is?

Steps to Reproduce

n/a

Expected Behavior

n/a

Current Behavior

n/a

Screenshots/Videos

No response

Client and System Information

n/a

[Mehgugs]

Some initial thoughts I had on this:

I think aiming for something similar to how threads are documented (with a dedicated topic as well as their channel documentation etc) would make things clearer. This also means some information can be moved from places like tables and specifications.

Should Application Role Connection Metadata be moved into Application? This would mean role_connections_verification_url is on the same page as that information.

The info callout below the metadata table is an example of something that could move to a new section and be expanded on.

There are a couple of surprising things when implementing this api that do need attention given to them, such as the string you pass to the oauth2 method. Things like "stringifying" a string metadata value (i.e the datetimes) could be defined with some examples.

[switchupcb]

the application's role connection verification entry point, which when configured will render the app as a verification method in the guild role verification configuration

What is a role connection? Why use it?

[Lulalaby]

the application's role connection verification entry point, which when configured will render the app as a verification method in the guild role verification configuration

What is a role connection? Why use it?

https://support.discord.com/hc/en-us/articles/10388356626711

[switchupcb]

https://support.discord.com/hc/en-us/articles/10388356626711
— @Lulalaby

Thanks.

---

@shaydewael You could add that (URL) to the documents near the role connections information too. Currently, you can't tell that it has any connection to linked roles from the resources or requests information in the documentation.

[Lulalaby]

I don't think the link is needed. Articles might change and stuff.

We could instead clarify what this feature is for. If it wasn't already noted.

[Lulalaby]

Even tho it's already explained enough

The support article is more for server admins

[switchupcb]

Where is the second screenshot found? This is the current page.

[Lulalaby]

Just search the docs 😅 Scrolling helps :p
https://discord.com/developers/docs/tutorials/configuring-app-metadata-for-linked-roles

[switchupcb]

How do I scroll??? xd