chore: finetune vale (#1585)

devalog · web-flow · commit 14aa465aa622 · 2025-10-29T16:49:36.000-04:00
diff --git a/.vale.ini b/.vale.ini
@@ -22,8 +22,10 @@ Microsoft.Vocab = NO
 Microsoft.Spacing = NO
 Microsoft.Semicolon = NO # Mostly just picks up code
 Microsoft.SentenceLength = NO # Mostly just picks up code
+Microsoft.Ellipses = NO # Mostly just picks up code
 Microsoft.Dashes = NO
 Microsoft.Foreign = NO
+Microsoft.Plurals = NO
 
 # Not relevant for Fern audience
 Microsoft.GeneralURL = NO
diff --git a/.vale/styles/FernStyles/Acronyms.yml b/.vale/styles/FernStyles/Acronyms.yml
@@ -75,3 +75,12 @@ exceptions:
   - OpenRPC
   - gRPC
   - RPC
+  - MCP
+  - JWT
+  - PUT
+  - GET
+  - POST
+  - IDE
+  - RBAC
+  - SAML
+  - OIDC
diff --git a/.vale/styles/FernStyles/Current.yml b/.vale/styles/FernStyles/Current.yml
@@ -13,6 +13,5 @@ tokens:
   - today
   - soon
   - latest
-  - new
   - upcoming
   - old
diff --git a/.vale/styles/FernStyles/Ellipses.yml b/.vale/styles/FernStyles/Ellipses.yml
diff --git a/.vale/styles/FernStyles/FirstPerson.yml b/.vale/styles/FernStyles/FirstPerson.yml
@@ -12,5 +12,4 @@ tokens:
   - \bI'm\b
   - \bI've\b
   - \bme\b
-  - \bmy\b
   - \bmine\b
diff --git a/.vale/styles/FernStyles/We.yml b/.vale/styles/FernStyles/We.yml
@@ -7,5 +7,4 @@ tokens:
   - we
   - we'(?:ve|re)
   - ours?
-  - us
   - let's
diff --git a/fern/products/docs/pages/api-references/api-ref-content.mdx b/fern/products/docs/pages/api-references/api-ref-content.mdx
@@ -55,7 +55,7 @@ By including the `summary` field, the `API Reference` section title will link to
 
 ## Adding Markdown content between endpoints
 
-In addition to adding Markdown content to individual endpoints, you can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints.
+You can also include Markdown content between endpoints in your API Reference. This content can provide context or explanations that apply to multiple endpoints.
 
 This feature requires you to use the `layout` field in your `docs.yml` file, which is described in the [Customize your API Reference](/learn/docs/api-references/customize-api-reference-layout) guide.
 
diff --git a/fern/products/docs/pages/api-references/autopopulate-api-key.mdx b/fern/products/docs/pages/api-references/autopopulate-api-key.mdx
@@ -1,5 +1,5 @@
 ---
-title: Auto-populate API keys
+title: Autopopulate API keys
 subtitle: Make integrating with your API frictionless by adding your login flow to the API Explorer.
 ---
 
@@ -25,9 +25,9 @@ API key injection can work in two different ways depending on your company's aut
 
 To enable this feature, you need to configure authentication so that Fern can securely retrieve API keys for your users. The process works as follows:
 
-1. When a user clicks the "Login" button in the API Explorer, they are redirected to your authentication page.
+1. When a user clicks the "Login" button in the API Explorer, they're redirected to your authentication page.
 2. After successful authentication, your system must set a cookie called `fern_token` in the user's browser.
-3. This token should be a [JWT](https://jwt.io) encrypted with a secret key that we provide. The JWT should contain the user's API key.
+3. This token should be a [JWT](https://jwt.io) encrypted with a secret key from Fern. The JWT should contain the user's API key.
 
 The JWT should have a structure similar to:
 
@@ -89,13 +89,13 @@ The JWT should have a structure similar to:
 
 <Markdown src="/snippets/jwt-auth-diagram.mdx"/>
 
-#### Setting up auto-populated API keys
+#### Setting up autopopulated API keys
 
 - [ ] Reach out to Fern to get your secret key
 - [ ] Send Fern the URL of your authentication page. This is where users will be redirected to after clicking the "Login" button in the API Explorer.
 - [ ] Add logic to your service to set the `fern_token` cookie when a user logs in
 
-<Tip>For an example of how to set up the `fern_token` cookie, see our demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts).</Tip>
+<Tip>For an example of how to set up the `fern_token` cookie, see this demo implementation [here](https://github.com/fern-api/fern-platform/blob/app/packages/fern-docs/bundle/src/app/%5Bhost%5D/%5Bdomain%5D/api/fern-docs/auth/fern-token-demo/route.ts).</Tip>
 
 </Accordion>
 <Accordion title="OAuth" toc={true}>
@@ -113,7 +113,7 @@ To enable this feature, you need to configure OAuth authentication so that Fern
 
 <Markdown src="/snippets/oauth-diagram.mdx"/>
 
-#### Setting up auto-populated API keys
+#### Setting up autopopulated API keys
 
 To enable API key injection, you'll need to:
 - [ ] Set up an authenticated account for Fern so Fern can authorize users on your behalf. 
diff --git a/fern/products/docs/pages/api-references/customize-api-ref.mdx b/fern/products/docs/pages/api-references/customize-api-ref.mdx
@@ -168,7 +168,7 @@ To customize the display of an endpoint, you can add a `title`. You can also use
 </Frame>
 
 ### Hiding endpoints
-You can hide an endpoint from the API reference by setting `hidden` to `true`. The endpoint will still be accessible at its URL.
+You can hide an endpoint from the API Reference by setting `hidden` to `true`. The endpoint will still be accessible at its URL.
 
 <Tabs>
   <Tab title="OpenAPI Specification">
@@ -267,7 +267,7 @@ navigation:
 
 ### Adding availability
 
-You can set the availability for the entire API reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. 
+You can set the availability for the entire API Reference or for specific sections. Options are: `stable`, `generally-available`, `in-development`, `pre-release`, `deprecated`, or `beta`. 
 
 ```yaml title="docs.yml" {3, 6}
 navigation: 
diff --git a/fern/products/docs/pages/api-references/generate-api-ref.mdx b/fern/products/docs/pages/api-references/generate-api-ref.mdx
@@ -19,7 +19,7 @@ navigation:
 | Property         | Value                                                                                                   |
 | ---------------- | ------------------------------------------------------------------------------------------------------- |
 | `api` (required) | Title of the API Reference Section                                                                      |
-| `api-name`       | Name of the API we are referencing, if there are [multiple APIs](#include-more-than-one-api-reference)  |
+| `api-name`       | Name of the API you're referencing, if there are [multiple APIs](#include-more-than-one-api-reference)  |
 | `audiences`      | List of [audiences](/docs/api-references/audiences) that determines which endpoints, schemas, and properties are displayed in your API Reference          |
 | `availability`   | Set the [availability status](/learn/docs/api-references/customize-api-reference-layout#adding-availability) for the entire API Reference or specific sections                           |
 | `display-errors` | Displays error schemas in the API References                                                            |
@@ -50,7 +50,7 @@ fern/
       └─ api.yml    # API definition
 ```
 
-For a simple setup without tabs, you can include multiple API references directly in your navigation:
+For a simple setup without tabs, you can include multiple API References directly in your navigation:
 
 ```yaml title="docs.yml"
 navigation:
@@ -60,7 +60,7 @@ navigation:
     api-name: garden-api  # Matches folder name containing your API definition
 ```
 
-When using tabs, each API reference must be placed within a tab's `layout`:
+When using tabs, each API Reference must be placed within a tab's `layout`:
 
 ```yaml title="docs.yml" {12, 17}
 tabs:
diff --git a/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx b/fern/products/docs/pages/api-references/generate-openrpc-ref.mdx
@@ -1,9 +1,9 @@
 ---
 title: Generate OpenRPC Reference
-description: Learn how to generate and customize OpenRPC API reference documentation
+description: Learn how to generate and customize OpenRPC API Reference documentation
 ---
 
-Fern enables you to generate professional, interactive API reference documentation for your JSON-RPC APIs using the [OpenRPC](https://open-rpc.org/) specification. OpenRPC provides a standardized, machine-readable format for describing JSON-RPC 2.0 APIs, unlocking powerful documentation and code generation workflows.
+Fern enables you to generate professional, interactive API Reference documentation for your JSON-RPC APIs using the [OpenRPC](https://open-rpc.org/) specification. OpenRPC provides a standardized, machine-readable format for describing JSON-RPC 2.0 APIs, unlocking powerful documentation and code generation workflows.
 
 <Frame caption={<a href="https://www.alchemy.com/docs/data/nft-api/api-reference/nft-ownership-endpoints/get-nf-ts-for-owner-v-3">Example of Alchemy's docs site</a>}>
   <img src="./alchemy-openrpc.png" alt="Alchemy's OpenRPC API Reference Example" />
diff --git a/fern/products/docs/pages/api-references/generate-websocket-ref.mdx b/fern/products/docs/pages/api-references/generate-websocket-ref.mdx
@@ -1,11 +1,11 @@
 ---
 title: Generate WebSocket Reference
-description: Learn how to generate and customize WebSocket API reference documentation
+description: Learn how to generate and customize WebSocket API Reference documentation
 ---
 
 <Markdown src="/snippets/pro-plan.mdx"/>
 
-Fern generates WebSocket API reference documentation from your AsyncAPI specification or Fern Definition. The AsyncAPI specification describes message-driven APIs in a machine-readable format. Fern supports the [v2](https://www.asyncapi.com/docs/reference/specification/v2.x) and [v3](https://www.asyncapi.com/docs/reference/specification/v3.0.0) specifications.
+Fern generates WebSocket API Reference documentation from your AsyncAPI specification or Fern Definition. The AsyncAPI specification describes message-driven APIs in a machine-readable format. Fern supports the [v2](https://www.asyncapi.com/docs/reference/specification/v2.x) and [v3](https://www.asyncapi.com/docs/reference/specification/v3.0.0) specifications.
 
 <Frame caption={<a href="https://developers.deepgram.com/reference/text-to-speech/speak-streaming">Example of how a WebSocket API Reference renders in Fern</a>}>
   <img src="websocket-deepgram.png" alt="WebSocket API Reference Example" />
diff --git a/fern/products/docs/pages/api-references/http-snippets.mdx b/fern/products/docs/pages/api-references/http-snippets.mdx
@@ -41,7 +41,7 @@ To generate HTTP snippets, add request examples to your API definition:
 
 ### Set default snippet language
 
-HTTP snippets support several languages. Our development work is driven by customer requests, so please request support for languages not listed here by [opening an issue](https://github.com/fern-api/fern/issues/new/choose).
+HTTP snippets support several languages. Fern development work is driven by customer requests – request support for languages not listed here by [opening an issue](https://github.com/fern-api/fern/issues/new/choose).
 
 * csharp
 * curl
diff --git a/fern/products/docs/pages/api-references/sdk-snippets.mdx b/fern/products/docs/pages/api-references/sdk-snippets.mdx
@@ -23,7 +23,7 @@ To configure SDK snippets, you'll need to name your SDKs in `generators.yml` and
 
 ### Add examples to your API definition
 
-In order to generate code snippets, Fern needs to read request examples from your API definition. If you're using a Fern Definition, you can follow [these instructions](/learn/api-definition/fern/examples). If you're using an OpenAPI Specification, you can follow [these instructions](https://swagger.io/docs/specification/adding-examples/).
+Fern needs to read request examples from your API definition to generate code snippets. If you're using a Fern Definition, you can follow [these instructions](/learn/api-definition/fern/examples). If you're using an OpenAPI Specification, you can follow [these instructions](https://swagger.io/docs/specification/adding-examples/).
 
 ### Define a package name for your SDK(s)
 
@@ -112,7 +112,7 @@ navigation:
 
 ### Trigger generation
 
-As the final step, trigger your docs generation by running `fern generate --docs` locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will now appear via a dropdown!
+As the final step, trigger your docs generation by running `fern generate --docs` locally or in CI/CD (i.e., GitHub Actions). The SDK snippets will appear via a dropdown!
 
 ### Set default snippet language
 
diff --git a/fern/products/docs/pages/authentication/overview.mdx b/fern/products/docs/pages/authentication/overview.mdx
@@ -5,14 +5,12 @@ description: Understand the different authentication options Fern offers
 
 Fern offers two methods of authentication, Single Sign-On (SSO) and Role-Based Access Control (RBAC). 
 
-**For most situations, we recommend using RBAC** for granular access control over your documentation. RBAC works well for sites with multiple audiences (internal teams, partners, customers) and supports API key injection to auto-populate code examples.
+**For most situations, use RBAC** for granular access control over your documentation. RBAC works well for sites with multiple audiences (internal teams, partners, customers) and supports API key injection to autopopulate code examples.
 
 API key injection can be set up using either JWT or OAuth, depending on your existing authentication system.
 
 **SSO is simpler** but only provides basic login functionality - it doesn't support RBAC or API key injection. SSO works well for internal-only documentation where everyone should see the same content.
 
-
-
 Learn more about Fern's authentication options:
 
 <CardGroup cols={3}>
diff --git a/fern/products/docs/pages/authentication/rbac.mdx b/fern/products/docs/pages/authentication/rbac.mdx
@@ -46,7 +46,7 @@ roles:
 
 ### Configure authentication via a `fern_token`
 
-Fern uses a browser cookie called `fern_token` to identify authenticated users and their roles. If this cookie is not present when a user tries to access restricted content, Fern redirects them to your login page.
+Fern uses a browser cookie called `fern_token` to identify authenticated users and their roles. If this cookie isn't present when a user tries to access restricted content, Fern redirects them to your login page.
 
 You can set up this authentication using either JWT or OAuth:
 
diff --git a/fern/products/docs/pages/authentication/set-up-oauth.mdx b/fern/products/docs/pages/authentication/set-up-oauth.mdx
@@ -61,7 +61,7 @@ Add a custom claim to your OAuth provider's token response. This claim will be u
 ```
 
 <Warning title="Using a claim other than `roles`">
-Some OAuth providers have strict requirements for custom claims. If you need to use a claim other than `roles`, please reach out to Fern and specify which claim should be parsed for the user's roles.
+Some OAuth providers have strict requirements for custom claims. If you need to use a claim other than `roles`, reach out to Fern and specify which claim should be parsed for the user's roles.
 </Warning>
 
 <AccordionGroup>
@@ -86,7 +86,7 @@ To add a custom claim to Auth0, you need to create a **custom action**. This act
 6. Add the action to your **Post Login Flow**.
 </Accordion>
 <Accordion title="Using another provider">
-If you are using a different OAuth provider, please reach out to Fern with any questions on setting up a custom claim.
+If you are using a different OAuth provider, reach out to Fern with any questions on setting up a custom claim.
 </Accordion>
 </AccordionGroup>
 </Step>

-Original file line number
+Diff line change
   - OpenRPC
   - gRPC
   - RPC
 +  - MCP
 +  - JWT
 +  - PUT
 +  - GET
 +  - POST
 +  - IDE
 +  - RBAC
 +  - SAML
 +  - OIDC