clarify info on fern definition section display name

Author: devalog

fern/products/api-def/ferndef-pages/endpoints.mdx

@@ -27,6 +27,10 @@ Each service defines:
   To define a service with an empty base path use the empty string: `base-path: ""`
 </Info>
 
+### Section display name
+
+By default, section names in your API Reference come from service file names (e.g., `user.yml` becomes "User"). To override the display name of a section, [use the `section` property in your `docs.yml`](/docs/api-references/customize-api-reference-layout#renaming-sections).
+
 ## Endpoints
 
 An endpoint includes:
@@ -41,7 +45,7 @@ An endpoint includes:
 - **Successful (200) response** information _(Optional)_
 - **Error (non-200) responses** that this endpoint might return _(Optional)_
 
-## URL path
+### URL path
 
 Each endpoint has a URL path.
 
@@ -63,7 +67,7 @@ The full path for the endpoint is the concatenation of:
 - The service `base-path`
 - The endpoint `path`
 
-## Display name
+### Endpoint display name
 
 The display name will appear as the title of an endpoint. By default, the display name is equal to the 'Title Case' of the endpoint name. If you would like to customize the endpoint name, you can **set the display name**. 
 
@@ -82,7 +86,7 @@ service:
 ```
 </CodeBlock>
 
-## Path parameters
+### Path parameters
 
 Supply path parameters for your endpoints to create dynamic URLs.
 
@@ -114,7 +118,7 @@ Services can also have path-parameters:
   ```
 </CodeBlock>
 
-## Query parameters
+### Query parameters
 
 Each endpoint can specify query parameters:
 
@@ -135,7 +139,7 @@ service:
 ```
 </CodeBlock>
 
-### `allow-multiple`
+#### `allow-multiple`
 
 Use `allow-multiple` to specify that a query parameter is allowed
 multiple times in the URL, as in `?filter=jane&filter=smith`. This will alter
@@ -152,7 +156,7 @@ parameter.
 ```
 </CodeBlock>
 
-## Auth
+### Auth
 
 Each endpoint can override the auth behavior specified in the service.
 
@@ -171,7 +175,7 @@ Each endpoint can override the auth behavior specified in the service.
   ```
 </CodeBlock>
 
-## Headers
+### Headers
 
 Each endpoint can specify request headers:
 
@@ -213,7 +217,7 @@ Services can also specify request headers. These headers will cascade to the ser
   ```
 </CodeBlock>
 
-## Request body
+### Request body
 
 Endpoints can specify a request body type.
 
@@ -232,7 +236,7 @@ service:
 ```
 </CodeBlock>
 
-### Inlining a request body
+#### Inlining a request body
 
 If the request body is an object, you can **inline the type declaration**. This
 makes the generated SDKs a bit more idiomatic.
@@ -255,7 +259,7 @@ makes the generated SDKs a bit more idiomatic.
   ```
 </CodeBlock>
 
-## Success response
+### Success response
 
 Endpoints can specify a `response`, which is the type of the body that will be
 returned on a successful (200) call.
@@ -279,7 +283,7 @@ types:
 ```
 </CodeBlock>
 
-## Response status codes 
+### Response status codes 
 
 You can also use the `status-code` field to specify a custom status code 
 for a success response. 
@@ -306,7 +310,7 @@ types:
 ```
 </CodeBlock>
 
-## Error responses
+### Error responses
 
 Endpoints can specify error responses, which detail the non-200 responses that
 the endpoint might return.
@@ -453,7 +457,7 @@ the request body, path parameters, query parameters, headers, and response body.
   ```
 </CodeBlock>
 
-### Failed examples
+#### Failed examples
 
 You can also specify examples of failed endpoints calls. Add the `error`
 property to a response example to designate which failure you're demonstrating.
@@ -490,7 +494,7 @@ errors:
 ```
 </CodeBlock>
 
-### Referencing examples from types
+#### Referencing examples from types
 
 To avoid duplication, you can reference examples from types using `$`.
 

fern/products/docs/pages/api-references/customize-api-ref.mdx

@@ -98,28 +98,28 @@ To reference an endpoint, you can use either:
 
 ### Renaming sections
 
-To override the display name of a section (created from tags in your API spec), 
-you can use the `section` property in your `docs.yml` and reference the original 
-tag name using `referenced-packages`.
+By default, section display names come from [service file names](/api-definition/fern/endpoints#service-definition) (Fern
+Definition) or tag names (OpenAPI) in your spec.
+
+To override the display name of a section, use the `section` property in your `docs.yml` and reference the `lowerCamelCase` version of the original service file name (Fern Definition) or tag name (OpenAPI) in `referenced-packages`.
 
 ```yaml title="docs.yml" {4-6}
 navigation: 
   - api: API Reference
     layout:
-      - section: "User" # New display name
+      - section: "Billing" # New section display name
         referenced-packages: 
-          - user-endpoint # Original tag name from your spec
+          - billing # lowerCamelCase version of original tag/service file name from your spec
         contents: []
-      - section: "Plant"
+      - section: "Bank Accounts"
         referenced-packages: 
-          - plant
+          - bankAccounts
         contents: []
 ```
 <Note>
-  You can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension (OpenAPI)](/api-definitions/openapi/extensions/tag-display-names) or the [`display-name` parameter (Fern Definition)](/api-definitions/ferndef/endpoints/overview#display-name)
+  For OpenAPI, you can alternatively customize tag display names directly in your spec (or `overrides.yml` file) using the [`x-displayName` extension](/api-definitions/openapi/extensions/tag-display-names). 
 </Note>
 
-
 ### Flattening sections
 To remove the API Reference title and display the section contents, set `flattened` to `true`.