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
There was a problem hiding this comment.
Agreed with @alexisintech here to be honest. For several reasons:
- The Authorization Checks page mentions organizations anyway
- There is a lot of repetition between the two pages, so it feels a bit redundant
- A lot of the code examples in the Authorization Checks page focuses on orgs
So yeah, not 100% convinced here that we need this page.
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 |
| @@ -1,6 +1,6 @@ | |||
| The `Organization` object holds information about an organization, as well as methods for managing it. | |||
|
|
|||
| To use these methods, you must have the **Organizations** feature [enabled in your app's settings in the Clerk Dashboard](/docs/guides/organizations/overview#enable-organizations-in-your-application). | |||
| To use these methods, you must have the **Organizations** feature [enabled in your app's settings in the Clerk Dashboard](/docs/guides/organizations/configure#enable-organizations). | |||
There was a problem hiding this comment.
Changing things directly within clerk-typedoc isn't possible, as that folder gets generated by changes in JSdocs comments within the javascript repo. So you'll need an additional PR on that repo to make that change. Happy to help! @im2nguyen
There was a problem hiding this comment.
NVM, just saw @alexisintech's PR for this. Will remove this tho.
| > [!IMPORTANT] | ||
| > This setting only applies to newly created organizations. Existing organizations retain their current deletion settings. | ||
| Learn more about [roles and permissions](/docs/guides/organizations/roles-and-permissions). |
There was a problem hiding this comment.
This feels out of place? It's already linked under Default roles, which feels more natural. Wondering if it's a mistake or here for a reason? @im2nguyen
| ## Switch between organizations | ||
|
|
||
| Users who belong to multiple organizations can switch between them at any time. The currently selected organization is called the active organization. | ||
|
|
||
| The [`<OrganizationSwitcher />`](/docs/reference/components/organization/organization-switcher) component provides the easiest way for users to switch between organizations. If you need more control over the switching logic, you can use the `setActive()` method from the [`useOrganizationList()`](/docs/reference/hooks/use-organization-list) hook, or access it directly from the [`Clerk`](/docs/reference/javascript/clerk#set-active) object. | ||
|
|
||
| If [personal accounts are enabled](/docs/guides/organizations/configure#allow-personal-accounts), users can also switch to their personal account using the `<OrganizationSwitcher />` component. |
There was a problem hiding this comment.
@im2nguyen This section feels redundant to me. It's already in the Overview, but also the section above makes it clear that you can use the <OrganizationSwitcher /> component to switch btw orgs. If we want to keep it though, I would remove that last paragraph, because the "you can also" feels as if it hasn't been mentioned before when it's right above (if that makes sense):
If [personal accounts are enabled](/docs/guides/organizations/configure#allow-personal-accounts), users can also switch to their personal account using the component.
| - `'user' | 'organization'` | ||
|
|
||
| A string that indicates whether the pricing table is for users or [organizations](/docs/guides/organizations/overview). If `'user'`, the pricing table will display a list of plans and features that **users** can subscribe to. If `'organization'`, the pricing table will display a list of plans and features that **organizations** can subscribe to. Defaults to `'user'`. | ||
| A string that indicates whether the pricing table is for users or [organizations](/docs/guides/organizations/create-and-manage). If `'user'`, the pricing table will display a list of plans and features that **users** can subscribe to. If `'organization'`, the pricing table will display a list of plans and features that **organizations** can subscribe to. Defaults to `'user'`. |
There was a problem hiding this comment.
Why the change of URL here? Wouldn't the overview still apply as this for a general view on organizations? @im2nguyen
| {{ style: { maxWidth: '436px' } }} | ||
|
|
||
| The `<OrganizationSwitcher />` component allows a user to switch between their joined organizations. If [personal accounts are enabled](/docs/guides/organizations/overview#allow-personal-accounts), users can also switch to their personal account. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. It handles all organization-related flows, including full organization management for admins. Learn more about [organizations](/docs/guides/organizations/overview). | ||
| The `<OrganizationSwitcher />` component allows a user to switch between their joined organizations. If [personal accounts are enabled](/docs/guides/organizations/configure#enable-organizations), users can also switch to their personal account. This component is useful for applications that have a multi-tenant architecture, where users can be part of multiple organizations. It handles all organization-related flows, including full organization management for admins. Learn more about [organizations](/docs/guides/organizations/create-and-manage). |
There was a problem hiding this comment.
@im2nguyen Same question applies for this one here:
Learn more about organizations.
| ### `Organization` | ||
|
|
||
| Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships. Users can belong to many organizations. One of them will be the [active organization](!active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/overview). | ||
| Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships. Users can belong to many organizations. One of them will be the [active organization](!active-organization) of the session. It is represented by the [`Organization`](/docs/reference/javascript/organization) object. To learn about organizations, see the [dedicated guide](/docs/guides/organizations/create-and-manage). |
There was a problem hiding this comment.
@im2nguyen Same question applies for this one here:
To learn about organizations, see the dedicated guide.
|
@im2nguyen @alexisintech have left a docs review pt2, with some minor refinements. It includes mostly the following:
For anything that raised question marks, I added a comment, and answered to the question around the need for the check access guide here. @im2nguyen let me know your thoughts on the docs review if any doubts, and I'll let you answer the comments too. |
|
Just doing triage, and there is this issue which could be tackled/ considered as part of this PR potentially. So putting it out there. 
|
🔎 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