feat(platform): add documentation for scoped API tokens

[tobice]

We're adding public facing documentation for a new feature, tokens with limited permissions, aka scoped tokens.

Full context is available in the design doc.

[tobice]

Hey folks, asking for early review. What's missing are screenshots, which I won't be able to provide before we finish the UI. However, the copy is final (= ready for review) from my PoV.

Also tagged @jirimoravcik as he is only semi-familiar with the project, so he'll be able to give useful feedback if the documentation is easy to understand / sufficiently detailed.

[fnesveda]

Let's put in some temporary screenshots (either the current state, or screenshots from Figma) until we finish the full UI, so that we can already craft the docs around them. Currently the docs are missing instructions on how to create scoped tokens, and what all the various permissions are.

I also think the API page should be displayed more prominently, not just two levels deep in Integrations, where it gets a bit lost. But that's a problem for another task.

[jirimoravcik]

Looks good to me, I'll also check when the screenshots are added

[tobice]

Updated the documentation:

• Added short instructions on how to create a scoped token
• Added 2 temporary screenshots, to be replaced with the actual ones once the UI is finished (I see no other use cases for screenshots)
• Unified callouts to use note across the board
• Minor copy changes

[tobice]

Currently the docs are missing [...], and what all the various permissions are.

Agreed with Franta that this is not necessary.

I also think the API page should be displayed more prominently, not just two levels deep in Integrations, where it gets a bit lost. But that's a problem for another task.

Hmm I guess. cc @TC-MO

[fnesveda]

👏 Good job, great docs 👍

[tobice]

Cool, thanks for the review ❤️

Let's wait now for Kuba and for how we decide to proceed with the UI. This means that the PR will stay open for a while.

[TC-MO]

Added a few changes to notes & headings

[drobnikj]

Changes look good, let's wait to final design implementation.

[tobice]

Uploaded new screenshots that use the new UI. Feel free to check it out @drobnikj

[tobice]

Alright, this PR is pretty much ready.

We synced with @TC-MO and made some changes together:

• We got rid of some of the gerunds in headings
• We kept the generic admotion titles ("Tip" / "Note") to see if people like them

I resolved all the pending conversions which were related to these topics.

@TC-MO @drobnikj feel free to take a look and approve 🙏

[TC-MO]

LGTM

[drobnikj]

🆒

[drobnikj]

I merged the public release to develop today, we can manage it to prod today.
Let's merge this @tobice

[tobice]

Won't make it to today's release. Lets's merge it tomorrow.