Reorganize and restructure Organization docs #2758
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR modifies files in the 'clerk-typedoc/' folder. These files are auto-generated from the clerk/javascript repository and should not be edited directly. To make changes to TypeDoc documentation:
Thanks for contributing! 🙏 |
|
| @@ -144,3 +155,12 @@ Use the following tabs to see examples for each method. | |||
| To use the JS Backend SDK to revoke an organization invitation, see the [`revokeOrganizationInvitation()`](/docs/reference/backend/organization/revoke-organization-invitation) reference documentation. | |||
| </Tab> | |||
| </Tabs> | |||
|
|
|||
| ## Next steps | |||
|
|
||
| > [!IMPORTANT] | ||
| > Personal accounts being disabled by default was released on August 22, 2025. Applications created before this date will not be able to see the **Allow personal accounts** setting, because personal account were enabled by default. | ||
| Organizations live within your Clerk application. Each application can contain multiple organizations, and each organization can have multiple users. You define roles and permissions once at the application level, and they apply across all organizations within that application. |
| Organizations live within your Clerk application. Each application can contain multiple organizations, and each organization can have multiple users. You define roles and permissions once at the application level, and they apply across all organizations within that application. | ||
|
|
||
| ## Organization slugs | ||
|  |
There was a problem hiding this comment.
if we want to keep this diagram, lets give it to our design team so they can flair it up with our clerk magic
There was a problem hiding this comment.
already have a ticket with Joshua to refresh this!
|
|
||
| This feature requires that [**Email** is enabled](/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email), as Clerk uses the user's email address to send the invitation. You can still disable **Email** as a sign-in option if you do not want users to be able to sign-in with their email address. | ||
|
|
||
| To configure your application's **Email** settings, navigate to the [**User & authentication**](https://dashboard.clerk.com/~/user-authentication/user-and-authentication) page in the Clerk Dashboard. | ||
|
|
||
| ## When to use invitations |
There was a problem hiding this comment.
I'm not convinced on this guide! We already have /authorization-checks
could you give me some of your thought process behind introducing this guide?
There was a problem hiding this comment.
the goal of having these "verb/" landing pages is for people who are completely unfamiliar with orgs to reorientate themselves
for example, adding members to your orgs. we support different ways to do that: invitations, verified domains (automatic suggestion/invitations), ent connections
based on the url itself, folks can grok/understand what the feature is doing
similar thing for "check-access", it's not supposed to be a top level. what the user cares about is "/control-access", to do that, they need to set up roles and permissions then checking access. the /authorization-check page is great but it covers authz checks in general (not org focused)
the check-access page should link out to /authorization-check and vice versa
alexisintech
force-pushed
the
im2nguyen/refactor-org-docs
branch
from
4d2de47 to
8b8d5cc
Compare
alexisintech
force-pushed
the
im2nguyen/refactor-org-docs
branch
from
8b8d5cc to
27bb678
Compare
|
I've left my docs review! take a look at the commit diff to see the changes :) I really like a lot of the additions/updates. We have a ticket in our Linear board to pull apart the organizations overview, I'm really glad that you got to tackle this - it's a great way to get comfortable with the organizations feature, and with our docs and how our voice/style is, and contributing to the docs in general. Overall, I think you're a great writer! You have a great eye for the overall organization of a doc, and how to present information to users. I loved this 😸💖 Some major things I changed:
I'm not sold on the overview - I think the "core flow" section needs a bit more work. I think the "Why organizations?" section is too marketing-y, very fluffy, and too much visual noise. but that's something we can chat about/tackle next week, because its friday and I'm logging off 🫡 if you have any questions at all about any of the updates I made, please don't hesitate to discuss with me. they are allllll open for discussion/change! |
|
I've updated these again - Overview:
Metadata:
unfortunately, I'm still not sold on the check-access guide for the reasons I mentioned - but I've updated the list in the overview to follow the structure you mentioned (regarding "add members" and "control access"), and pointed to the /authorization-checks guide. but I see where you're coming from and don't want to undermine your contribution!!! so lets ask for a third opinion @SarahSoutoul |
🔎 Previews:
https://clerk.com/docs/pr/im2nguyen-refactor-org-docs/guides/organizations/overview
This PR updates the Organization docs so the value proposition is clear. In addition, it breaks apart the current "Overview" page so it's easier to parse.
Checklist