From d1af5ba2ee287960d2d4231817af0b215667eec8 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Wed, 4 Dec 2024 17:32:06 -0500 Subject: [PATCH 1/2] Update styleguides --- docs/deployments/deploy-chrome-extension.mdx | 4 +- docs/users/deleting-users.mdx | 2 +- styleguides/SSO.STYLEGUIDE.MD | 154 +----- styleguides/STYLEGUIDE.md | 465 +++++++------------ 4 files changed, 183 insertions(+), 442 deletions(-) diff --git a/docs/deployments/deploy-chrome-extension.mdx b/docs/deployments/deploy-chrome-extension.mdx index 33ada0d783..609cd33bf6 100644 --- a/docs/deployments/deploy-chrome-extension.mdx +++ b/docs/deployments/deploy-chrome-extension.mdx @@ -17,7 +17,7 @@ For Clerk production instances, there must be a domain associated with the insta - 1. At the top in the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. + 1. At the top of the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. 1. In the navigation sidebar, select [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys). 1. In the **Quick Copy** section, select **Chrome Extension** and copy your Clerk Publishable and Frontend API keys. 1. Paste your keys into your `.env.production` file. @@ -64,7 +64,7 @@ The following example shows how to configure `host_permissions` for production: - 1. At the top in the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. + 1. At the top of the Clerk Dashboard, in the instance selection dropdown, ensure that your production instance is selected. 1. In the navigation sidebar, select [**API keys**](https://dashboard.clerk.com/last-active?path=api-keys). 1. Copy your Secret Key. It should begin with `sk_live_`. 1. In your terminal, paste the following command. Replace `YOUR_SECRET_KEY` with your Clerk Secret Key and the `` with your extension's ID. diff --git a/docs/users/deleting-users.mdx b/docs/users/deleting-users.mdx index 3c2586a37a..6e9e74bf12 100644 --- a/docs/users/deleting-users.mdx +++ b/docs/users/deleting-users.mdx @@ -9,7 +9,7 @@ There are two ways to delete users in Clerk: [through the Clerk Dashboard](#dele To delete users in the Clerk Dashboard: -1. At the top in the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). +1. At the top of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). 1. You can either select the user and then in the side navigation menu, select **Delete user**, or select the menu icon on the right side of the user's row and select **Delete user**. ## Delete users using the Clerk API diff --git a/styleguides/SSO.STYLEGUIDE.MD b/styleguides/SSO.STYLEGUIDE.MD index d5dd940c85..b3d42b4871 100644 --- a/styleguides/SSO.STYLEGUIDE.MD +++ b/styleguides/SSO.STYLEGUIDE.MD @@ -55,18 +55,7 @@ These are the guidelines we use to write our SSO guides. Screenshots should be used little to none in the docs. The instructions should be explicit and include all necessary details without the need for a visual reference. The instructions should be laid out as numbered lists to make the content more palatable to readers. Links should be added on their first reference. -### Do - -```mdx -1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. -1. Select **Add connection** and select **For all users**. -1. In the **Choose provider** dropdown, select **Microsoft**. -1. Select **Add connection**. -``` - -### Don't - -In this example, the instructions are not explicit, as it tells the reader to select **Microsoft** but doesn't specify where to find it. +> ❌ In the example below, the instructions are not explicit, as it tells the reader to select **Microsoft** but doesn't specify where to find it. ```mdx 1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. @@ -75,162 +64,59 @@ In this example, the instructions are not explicit, as it tells the reader to se 1. Select **Microsoft**. ``` -## Bold proper nouns - -Bold proper nouns found in the UI, such as titles, headings, product names, etc. - -An exception to this rule is the Clerk Dashboard, which doesn't need to be bolded to enforce consistency across the docs. - -### Do - -```mdx -In the **Azure services** section, select **Microsoft Entra ID**. -``` - -### Don't +> ✅ In the example below, the instructions are explicit and include all necessary details without the need for a visual reference. ```mdx -In the Azure services section, select Microsoft Entra ID. +1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page. +1. Select **Add connection** and select **For all users**. +1. In the **Choose provider** dropdown, select **Microsoft**. +1. Select **Add connection**. ``` ## Writing about redirects If the step ends with a redirect, include the redirect instructions in the step. -### Do - -1. Select **New application**. You'll be redirected to the . -1. Select **Create your own application**. - -### Don't +> ❌ +```mdx 1. Select **New application**. 1. In the ****, select **Create your own application**. - -## Component naming - -The proper names for the components are: - -- Dashboard: refers to a control panel or central hub where users can interact with multiple tools or view data -- Panel: drawer -- Modal: popup -- Dropdown - -## Use conjunctions - -Use conjunctions in the copy to make the copy more colloquial. - -### Do - -"You'll" - -### Don't - -"You will" - -## Avoid using "button" - -### Do - -```mdx -1. Select **New client secret**. ``` -### Don't +> ✅ ```mdx -1. Select the **New client secret** button. -``` - -## Avoid using "click" - -### Do - -```mdx -1. Select **New client secret**. -``` - -### Don't - -```mdx -1. Click **New client secret**. -``` - -## Avoid using "appears" - -### Do - -```mdx -In the panel that opens -``` - -### Don't - -```mdx -In the panel that appears +1. Select **New application**. You'll be redirected to the . +1. Select **Create your own application**. ``` -## Action verbs - -- Add: general use (e.g., Add your app information) -- Enter: general typing (e.g., Enter your email address) -- Paste: to copy and paste values (e.g., Paste the Client ID you copied from the Clerk Dashboard) -- Complete: to fill out forms - -## Application vs. app - -Use "application" for the first instance where it's used and then "app" for the rest of the guide. - -## Redirected to vs. taken to - -Use "redirected to" instead of "taken to." +## Page vs. tab -## Ensure vs. make sure - -Use "ensure" instead of "make sure." - -### Do - -```mdx -On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. -``` +Assume users are opening windows versus browser tabs. Use active voice (e.g., "keep" vs. "leave). -### Don't +> ❌ The first example is wrong because it uses "leave" instead of "keep" and "tab" instead of "page." ```mdx -On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be taken to the **Certificate & secrets** page. +Leave the tab open. ``` -## Page vs. Tab - -Assume users are opening windows versus browser tabs. Use active voice (e.g., "keep" vs. "leave). - -### Do +> ✅ This example is correct because it uses "keep" and "page". ```mdx Keep the page open. ``` -### Don't +## Complete vs. fill out -```mdx -Leave the page open. -``` +> ❌ ```mdx -Leave the tab open. +Fill out the form as follows ``` -## Complete vs. Fill out - -### Do +> ✅ ```mdx Complete the form as follows ``` - -### Don't - -```mdx -Fill out the form as follows -``` diff --git a/styleguides/STYLEGUIDE.md b/styleguides/STYLEGUIDE.md index 4a6de61262..858fcd020d 100644 --- a/styleguides/STYLEGUIDE.md +++ b/styleguides/STYLEGUIDE.md @@ -2,451 +2,306 @@ These are the guidelines we use to write our docs. -## 1. Write with consistency +## Content (grammar/structure) -### 1.1 Use American English +### De-dupe reference links -Clerk is an American company and the epicenter of our development community is located in America's tech community. For that reason, we use the American flavor of English (as opposed to British English). - -#### Do - -> You might not realize it, but you can change the colors of your Clerk components with global CSS. - -#### Don't - -> You might not realise it, but you can change the colours of your Clerk components with global CSS. - -### 1.2 Hyphens? Spaces? Neither! - -Tech has created many new words by associating two words with each other like "front end" and "web site." On a long enough timeline, these migrate to hyphenated forms: "web site" became "web-site." And finally they become concatenated words: "website." We use the concatenated forms. - -#### Do - -> Frontend and fullstack developers often build websites with React. - -#### Don't - -> Front-end and full stack developers often build web-sites with React. - -### 1.3 De-dupe reference links - -When mentioning a documented component, function, etc, multiple times on a page, link to the reference documentation on the first mention of that item. The exception to this rule is when the reference is mentioned under a different heading. In that case, link to the reference documentation again. - -#### Do - -> The [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper will return the [`User`](https://clerk.com/docs/references/javascript/user/user) object of the currently active user. The following example uses the `currentUser()` helper to access the `User` object for the authenticated user. - -#### Don't +When mentioning a documented component, function, etc, multiple times on a page, link to the reference documentation on the **first mention** of that item. The exception to this rule is when the reference is mentioned under a different heading. In that case, link to the reference documentation again. +> ❌ > The [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper will return the [`User`](https://clerk.com/docs/references/javascript/user/user) object of the currently active user. The following example uses the [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper to access the [`User`](https://clerk.com/docs/references/javascript/user/user) object for the authenticated user. -### 1.4 Write out abbreviations when introducing them - -If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. If you want to make an abbreviation plural treat them as regular words, e.g. APIs, IDEs or OSes. - -#### Do - -> An abstract syntax tree (AST) is a tree representation of code. ASTs are a fundamental part of the way a compiler works. - -#### Don't - -> An AST is a tree representation of code. AST's are a fundamental part of the way a compiler works. - -### 1.5 Use sentence case for titles - -#### Do +> ✅ +> The [`currentUser()`](https://clerk.com/docs/references/nextjs/current-user) helper will return the [`User`](https://clerk.com/docs/references/javascript/user/user) object of the currently active user. The following example uses the `currentUser()` helper to access the `User` object for the authenticated user. -> ## How to set up custom pages +### Use sentence-case for titles -#### Don't +> ❌ +> How to Set up Custom Pages -> ## How to Set up Custom Pages +> ✅ +> How to set up custom pages -### 1.5 When referring to Next.js proper nouns, follow Next.js's capitalization conventions +### When referring to Next.js proper nouns, follow Next.js's capitalization conventions "Middleware," "Server Actions," "Server Components," "Route Handlers" are capitalized in the Next.js docs and in Clerk's docs where referring to a Next.js project or code. -#### Do +> ❌ +> Add it to your app's middleware. +> ✅ > Add it to your app's Middleware. -#### Don't +### Use "Sign in", not "Log in" -> Add it to your app's middleware. - -### 1.6 Use "Sign in", not "Log in" - -When referring to Clerk's SDKs, components, and dashboard, use "sign in" and "sign out" rather than "log in" or "log out". This is consistent with our `` component and `SignIn` class. +Use "sign in" and "sign out" rather than "log in" or "log out". -#### Do +> ❌ +> `` creates a button that allows users to log into your Clerk application. +> ✅ > `` creates a button that allows users to sign into your Clerk application. -#### Don't +### Write out abbreviations when introducing them -> `` creates a button that allows users to log into your Clerk application. - -## 2. Write for clarity - -### 2.1 “You” is the reader; "Clerk" is Clerk +If you want to abbreviate a term in your article, write it out fully first, then put the abbreviation in parentheses. If you want to make an abbreviation plural treat them as regular words, e.g. APIs, IDEs or OSes. -Clerk is the entity writing these docs and providing these services. The learner is the person consuming these things and building their own projects. To distinguish between the two and write with clarity, we refer to the learner with "you/your/yours." We objectively refer to Clerk as "Clerk," not "we/us/our/ours." +> ❌ +> An AST is a tree representation of code. AST's are a fundamental part of the way a compiler works. -#### Do +> ✅ +> An abstract syntax tree (AST) is a tree representation of code. ASTs are a fundamental part of the way a compiler works. -> Clerk's `` provides active session and user context to Clerk's hooks and other components. Import it into your app by adding `import { ClerkProvider } from '@clerk/nextjs'` at the top of your file. +### Avoid "we/us/our/ours" -#### Don't +We refer to the reader with "you/your/yours." We objectively refer to Clerk as "Clerk," not "we/us/our/ours." +> ❌ > Our `` provides active session and user context to our hooks and other components. Let's import it into our app by adding `import { ClerkProvider } from '@clerk/nextjs'` at the top of the file. -### 2.2 "Users" are people logging in/out with Clerk. "Developers" are the audience we’re writing for. - -People building with clerk are building for other people to make it clear whether we are talking about the builder or their users, we call builders "developers" and the peoeple they are building for "users." - -#### Do - -> Clerk helps developers overcome as many challenges as possible without additional configuration. This ensures their users have a secure, safe session. - -#### Don't - -> Clerk helps users overcome as many challenges as possible without additional configuration. This ensures their users have a secure, safe session. - -### 2.3 Shorter is better - -Write short sentences. Short sentences are easier for both human and robots to translate. Concise writing is understandable writing. Look for commas that string together different thoughts. These are often good places to shorten and clarify content. +> ✅ +> Clerk's `` provides active session and user context to Clerk's hooks and other components. Import it into your app by adding `import { ClerkProvider } from '@clerk/nextjs'` at the top of your file. -#### Do +## Use conjunctions -> Clerk is now installed and mounted in your application. You can decide which pages are public or require authentication to access. +Use conjunctions in the copy to make the copy more colloquial. -#### Don't +> ❌ +> "You will" -> Now that Clerk is installed and mounted in your application, you can decide which pages are public and which should require authentication to access. +> ✅ +> "You'll" -### 2.4 Avoid gerunds (-ing words) +### Avoid gerunds (-ing words) English gerunds ("-ing" words like "running") turn verbs into nouns ("run" becomes "running"). This makes the sentence sound passive ("They run" becomes "they are running") and makes it harder to translate. Use an active voice as much as possible and avoid these words. -#### Do - -> How to use a routing library with Clerk - -#### Don't - +> ❌ > Using a routing library with Clerk -### 2.5 Use task and outcome-based headings and titles that use verbs. - -Tell the learner what they will learn from diving into the content. - -#### Do - -> How to read session and user data - -> How user sessions and user data work - -Clearly explains what information the learner will find, helping them decide which to choose. - -#### Don't - -> User session and user data - -Obscure. Doesn't convey whether this is the conceptual or task-based content the learner is looking for. They may pass over it or look briefly, then bounce out. This increases friction. +> ✅ +> How to use a routing library with Clerk -### 2.6 Lead with location; end with action. +### Lead with location; end with action. When learners are performing an order of operations, it helps for them to start with _where_ they need to be to perform the action. -#### Do - -> In your Next.js project's root folder, open your `.env.local file`. - -The learner navigates to the project folder first, opens the file second. - -#### Don't - +> ❌ > Open your `.env.local file` in your Next.js project's folder. -The learner must remember the file they need to open before finding out which folder to navigate to. This uses more mental energy. - -### 2.7 Avoid colloquialisms - -English speakers may find themselves using phrases which cultural meaning may be different around the world. - -#### Do - -> Something that is difficult for someone new to programming may not be for a senior engineer. - -#### Don't - -> Something that is difficult for someone new to programming may be child's play for a senior engineer. - -Some learners may not have heard this expression before. It may be difficult for machine translation as well. +> ✅ +> In your Next.js project's root folder, open your `.env.local file`. -### 2.8 Use a active voice vs. passive voice. +### Use an active voice vs. passive voice Use active verbs that put the reader in the first person instead of passive verbs; "be" verbs that describe the learners actions as a state of being, like "is/was/to be". -#### Do - -> Create the `middleware.ts` file in the root folder of your application or inside the `src/` if that is how your app is set up. - -#### Don't - +> ❌ > The `middleware.ts` file should be created in the root folder of your application or inside `src/` if that is how you set up your app. -## 3. Write to include people - -### 3.1 Do not assume proficiency - -Avoid using language that assumes someone's level of proficiency. Something that is difficult for someone new to programming may not be difficult for a senior engineer. This language can inadvertently alienate or insult a learner. Avoid words like "just," "easy," "simple," "senior," "hard." - -Use as little [jargon](https://dictionary.cambridge.org/dictionary/english/jargon) as necessary. Describe jargon in parentheses on first reference or link to a trusted definition. - -#### Do - -> You can authenticate your app with Clerk in three steps. Install Clerk with `npm install @clerk/nextjs`, add your environment variables, and then wrap your app in ``, and add [control components](https://clerk.com/docs/components/overview). Visit our [Quickstarts](https://clerk.com/docs/quickstarts/overview) for a step-by-step guide written for your framework. - -> Clerk supports offline mode, a feature that lets users use an app without being connected to data or wifi. This means Clerk works great with progressive web apps, apps built with web platform technologies that provide similar experiences to platform-specific apps. You can use the [dynamic import pattern](https://www.patterns.dev/vanilla/dynamic-import) to improve loading speeds. +> ✅ +> Create the `middleware.ts` file in the root folder of your application or inside the `src/` if that is how your app is set up. -#### Don't +> ❌ +> User session and data -> It's easy to authenticate your app with Clerk! Just install Clerk with `npm install @clerk/nextjs`, add your environment variables, wrap your app in ``, and simply add [control components](https://clerk.com/docs/components/overview). +> ✅ +> Read user session and data -> Clerk works great with PWA as it supports offline mode. You can use the dynamic import pattern to improve loading speeds. +### Bold proper nouns -### 3.2 Avoid pop culture references +Bold proper nouns found in the UI, such as titles, headings, product names, etc. -It's tempting to use things that are familiar to us to explain things to others—our favorite TV shows, books, and memes are entertaining and rich sources of metaphors. However, they assume a shared context between author and reader. A joke that mainstream American audiences understand may be completely misunderstood to a learner in Chile. +An exception to this rule is "the Clerk Dashboard", which doesn't need to be bolded because it's referenced often in the docs and we want to avoid too much visual noise. -#### Do +> ❌ -```js -const updateUser = async () => { - await user.update({ - firstName: 'John', - lastName: 'Doe', - }) -} +```mdx +In the Azure services section, select Microsoft Entra ID. ``` -#### Don't +> ✅ -```js -const updateUser = async () => { - await user.update({ - firstName: 'Twilight', - lastName: 'Sparkle', - }) -} +```mdx +In the **Azure services** section, select **Microsoft Entra ID**. ``` -This assumes the learner is familiar with the cartoon _My Little Pony: Friendship is Magic,_ which is irrelevant. - -### 3.3 Use "they/them/theirs" pronouns - -For many years it was common to write with "he/him/his" pronouns in English technical documentation. But pronouns are difficult to translate into some languages. Gendering learners also sends the message that some genders are "default"—and this might not be the learner's gender. We use the neutral "they/them/theirs" pronouns. - -#### Do - -> When the user logs out using the button, they will be taken to the sign-in page. - -#### Don't - -> When he logs out using the button, he will be taken to the sign-in page. - -### 3.4 Avoid "click" - -"Click" is an outdated term that assumes the learner is using a mouse. But learners may be navigating by touchscreen, keyboard, or assistive technology. Often there are better words than "click"—like "select" and "open". +### Component naming -#### Do +The proper names for the components are: -> Open the **Settings tab.** - -> Select the **Google** social connection. - -#### Don't - -> Click the **Settings tab.** - -> Click the **Google** social connection. - -## 4. Write for code - -### 4.1 Use monospace fonts for code, commands, file names, copy-ables, and URLs; use bold for menus, and other UI copy. - -#### Do - -> In the Clerk Dashboard, go to **User & Authentication > [Social Connections](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections)** and open the **Settings** tab. - -> In your browser, open [`http://localhost:3000/`](http://localhost:3000/). - -#### Don't - -> In the [Clerk Dashboard](https://dashboard.clerk.com/), go to `User & Authentication > Social Connections` and open the "Settings tab." - -> In your browser, open [`http://localhost:3000/`](http://localhost:3000/). +- Dashboard: refers to a control panel or central hub where users can interact with multiple tools or view data +- Panel: drawer +- Modal: popup +- Dropdown -### 4.2 Use carets to help users navigate menus +### Application vs. app -Use carets to nest operations of the same type like menu navigation. +Use "application" for the first instance where it's used and then "app" for the rest of the guide. -#### Do +### Redirected to vs. taken to -> In the [Clerk Dashboard](https://dashboard.clerk.com/), go to **User & Authentication > [Social Connections](https://dashboard.clerk.com/last-active?path=user-authentication/social-connections)** and open the **Settings tab.** +Use "redirected to" instead of "taken to." -#### Don't +> ❌ -> In the [Clerk Dashboard](https://dashboard.clerk.com/), go to **User & Authentication**, click on **Social Connections**, and open the **Settings tab.** - -### 4.3 Write compliant JSON: no single quotes, no comments - -Conform to the [JSON standard](https://www.json.org/json-en.html): - -- Key names are enclosed in double quotes (`"`) -- Values are between double quotes (`"`), not single quotes (`'`) -- No comments, neither `//` nor `/* */` - -#### Do - -> This is the user's primary email address in the User object - -```json -{ - "email": "{{user.primary_email_address}}" -} +```mdx +On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be taken to the **Certificate & secrets** page. ``` -#### Don't +> ✅ -```json -{ - // this is the user's primary email address in the User object - "email": "{{user.primary_email_address}}" -} +```mdx +On this same page, under **Client credentials**, select **Add a certificate or secret** to generate a Client Secret. You'll be redirected to the **Certificate & secrets** page. ``` -### 4.4 Use 2-space indents for code blocks +## Ensure vs. make sure -We use 2-space indents to conserve horizontal space in code blocks. +Use "ensure" instead of "make sure." -#### Do +> ❌ +> Make sure you have the correct permissions. -```js -export const config = { - matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'], -} -``` +> ✅ +> Ensure you have the correct permissions. -#### Don't +## Accessibility -```js -export const config = { - matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'], -} -``` +### Do not assume proficiency + +Avoid using language that assumes someone's level of proficiency. Something that is difficult for someone new to programming may not be difficult for a senior engineer. This language can inadvertently alienate or insult a learner. Avoid words like "just", "easy", "simple", "senior", "hard". -### 4.5 Authentication states should be hyphenated and bold. +Use as little [jargon](https://dictionary.cambridge.org/dictionary/english/jargon) as necessary. Describe jargon in parentheses on first reference or link to a trusted definition. -Clerk authentication states **signed-in**, **signed-out**, and **unknown** should be hyphenated and bold to distinguish them from general states of being. +> ❌ +> It's _easy_ to authenticate your app with Clerk! -#### Do +> ✅ +> You can authenticate your app with Clerk in three steps. -> Once you have a **signed-in** user, you need to give them a way to sign out. +> ❌ +> Clerk works great with PWA as it supports offline mode. -#### Don't +> ✅ +> Clerk supports offline mode, a feature that lets users use an app without being connected to data or wifi. -> Once you have a signed-in user, you need to give them a way to sign out. +### Avoid "click" -### 4.6 Group like with like under tabs +"Click" is an outdated term that assumes the learner is using a mouse. But learners may be navigating by touchscreen, keyboard, or assistive technology. Often there are better words than "click", like "select" and "open". -When presenting things in a series of tabs, ensure that similar things are grouped together. +> ❌ +> Click the **Settings tab.** +> +> Click the **Google** social connection. -#### Do +> ✅ +> Open the **Settings tab.** +> +> Select the **Google** social connection. -![App Router and Pages Router exist as two tabs, side by side](/.github/media/uncrowded-tabs.png) +### Avoid using "button" -Next.js is a platform with two different implementations grouped underneath it. +> ❌ Select the **New client secret** button. -#### Don't +> ✅ Select **New client secret**. -![App Router and Pages Router are sitting alongside other very different methods of retrieving data](/.github/media/crowded-tabs.png) +## Code -Next.js's two implementations are given equal weight to the other members of the tab bar. Someone unfamiliar with Next.js may become confused, and the ever growing tab bar is harder to navigate at smaller sizes. +### Use monospace fonts for code, commands, file names, and URLs -### 4.7 Wrap component references in the appropriate tags +> ❌ +> Copy the environment variables to your .env file. -Component references should be wrapped in `< />` if they are self closing. Otherwise, they should be wrapped in `< >`. +> ✅ +> Copy the environment variables to your `.env` file. -#### Do +> ❌ +> In your browser, open http://localhost:3000/. -> Use the `` component. +> ✅ +> In your browser, open [`http://localhost:3000/`](http://localhost:3000/). -> Use the `` component. +### Wrap component references in the appropriate tags -#### Don't +Component references should be wrapped in `< />` if they are self closing. Otherwise, they should be wrapped in `< >`. +> ❌ > Use the `` component. +> ❌ > Use the "SignIn component". +> ❌ > Use the `SignIn` component. +> ❌ > Use the `` component. The last case is incorrect because the `` component will never wrap children, and therefore, should have a self-closing tag. -> Use the `` component. - -The last case is incorrect because the `` component will always wrap children and will never be self-closing. +> ✅ +> Use the `` component. -### 4.8 Specify syntax and filename for terminal commands +### Specify syntax and filename for terminal commands If the code should run in a terminal, set the code block's syntax highlighting and filename with `sh filename="terminal"`. -#### Do +> ❌ ```` -​```sh {{ filename: 'terminal' }} +​``` npm i @clerk/nextjs ​``` ```` -#### Don't +> ✅ ```` -​``` +​```sh {{ filename: 'terminal' }} npm i @clerk/nextjs ​``` ```` -### 4.9 Pass properties to components; Parameters to functions +### Pass properties to components; parameters to functions Be sure to use the correct term with components vs functions. -> Be sure to use the appropriate terms on reference page headings. - -#### Do +> ❌ +> The `` component accepts the `signUpProps` parameter. The `buildUrlWithAuth()` function accepts the `to` property. +> ✅ > Pass the `signUpProps` property to ``. `buildUrlWithAuth()` accepts a `string` for the `to` parameter. -#### Don't - -> The `` component accepts the `signUpProps` parameter. The `buildUrlWithAuth()` function accepts the `to` property. +## Page navigation -### 4.10 Provide users with clear instructions and a direct link when navigating the Clerk Dashboard +### Provide users with clear instructions and a direct link when navigating the Clerk Dashboard When instructing learners to perform an operation in the Clerk Dashboard, begin with "In the Clerk Dashboard" and end with a link to the page you're directing them to using this URL syntax: **`https://dashboard.clerk.com/last-active?path=PAGE`** -#### Do +> ❌ +> Go to **User & Authentication** in your dashboard. -> In the Clerk Dashboard, navigate to **[User & Authentication](https://dashboard.clerk.com/last-active?path=user-authentication)** page. +> ✅ +> In the Clerk Dashboard, navigate to the [**User & Authentication**](https://dashboard.clerk.com/last-active?path=user-authentication) page. +> ❌ +> Find fallback redirects in the Redirect tab on the Account Portal in the Clerk Dashboard. + +> ✅ > To specify the fallback redirects, in the Clerk Dashboard, go to the **[Account Portal](https://dashboard.clerk.com/last-active?path=account-portal)** page and open the **Redirects** tab. -#### Don't +### Avoid using "appears" -> Go to **User & Authentication** in your dashboard. +> ❌ +> A modal will appear. -> Find fallback redirects in the Redirect tab on the Account Portal in the Clerk Dashboard. +> ✅ +> A modal will open. + +### Address the top of the Clerk Dashboard + +> ❌ +> In the top navigation bar of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). + +> ✅ +> At the top of the Clerk Dashboard, select [**Users**](https://dashboard.clerk.com/last-active?path=users). From f3dc9c3dec6b981ea372da5dc442efcd2571c58d Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Fri, 6 Dec 2024 11:12:02 -0500 Subject: [PATCH 2/2] syntax for code example explanations --- styleguides/STYLEGUIDE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/styleguides/STYLEGUIDE.md b/styleguides/STYLEGUIDE.md index 858fcd020d..7f463a3661 100644 --- a/styleguides/STYLEGUIDE.md +++ b/styleguides/STYLEGUIDE.md @@ -165,6 +165,14 @@ Use "ensure" instead of "make sure." > ✅ > Ensure you have the correct permissions. +### Syntax for code example explanations + +Code examples should always have an explanation preceding them. Typically, they begin with something along the lines of "The following example demonstrates..." + +> ❌ You might have already configured ``. Ensure that `` wraps `ConvexProviderWithClerk` and that `useAuth` is passed to `ConvexProviderWithClerk`. + +> ✅ The following example demonstrates how to configure Clerk and Convex's providers. Clerk's `useAuth()` hook must be passed to `` and Clerk's `` must be wrapped around it. + ## Accessibility ### Do not assume proficiency