docs: update availability documentation (#3078)

* docs: document x-fern-availability openapi extension

* docs: add details about how to use availability component

* docs: wording update

* docs: update desc of generally-available availability property behavior

fern/docs/pages/fern-docs/content/components/availability.mdx

@@ -1,33 +1,37 @@
 ---
 title: Fern | Indicate the Availability of an endpoint
-description: Indicate the status of an endpoint using the Availability component. Display whether the endpoint is in beta, generally available, or deprecated. 
+description: Indicate the status of a feature using the Availability component. Display a tag of beta, generally available, or deprecated. 
 ---
 
-The `Availability` component is used to indicate the availability status of an endpoint.
+The `Availability` component is used to indicate the availability status of a feature, such as an endpoint. This component renders as a tag within your documentation.
 
-Availability Prop:
+Within the API reference documentation generated using Fern Docs, use the [Fern Definition `availability`](/overview/define-your-api/ferndef/availability) property or the [OpenAPI extension `x-fern-availability`](/overview/define-your-api/openapi/extensions) to indicate availability. 
+
+In the Markdown/MDX pages that make up the rest of your documentation site, use the `Availability` component as shown below to render the tag.
+
+Availability prop:
 
 **type**: 'beta' | 'GA' | 'deprecated'
 
 ## Beta availability 
 
-Indicates that an endpoint is in <Availability type="beta" />. This means that the endpoint is still in development and may change before it is released to the public. 
+Indicates that a feature is in <Availability type="beta" />. This means that the feature is still in development and may change before it is released to the public. 
 
 ```mdx
 <Availability type="beta" />
 ```
 
 ## General availability
 
-Indicates that an endpoint is <Availability type="GA" />. This means that the endpoint is ready for use in production. 
+Indicates that a feature is <Availability type="GA" />. This means that the feature is ready for use in production. 
 
 ```mdx
 <Availability type="GA" />
 ```
 
 ## Deprecated availability
 
-Indicates that an endpoint is <Availability type="deprecated" />. This means that the endpoint is no longer supported and will be removed in a future release.
+Indicates that a feature is <Availability type="deprecated" />. This means that the feature is no longer supported and will be removed in a future release.
 
 ```mdx
 <Availability type="deprecated" />

fern/docs/pages/overview/define-your-api/ferndef/availability.mdx

@@ -1,12 +1,10 @@
 You can add `availability` to an endpoint, type, or property within your Fern Definition.
 
 Availability can be:
-- `in-development` which means it is being worked on; will show a `beta` tag
-- `pre-release` which means it is available; will show a `beta` tag
-- `deprecated` which means it will be removed in the future; will show a `deprecated` tag
-- `generally-available` which means it is stable and available for use; will not show a tag
-
-By default, all endpoints, types, and properties are `generally-available`.
+- `in-development` which means it is being worked on; will show a `Beta` tag
+- `pre-release` which means it is available; will show a `Beta` tag
+- `deprecated` which means it will be removed in the future; will show a `Deprecated` tag
+- `generally-available` which means it is stable and available for use; will show a `GA` tag
 
 ## Endpoint 
 
@@ -91,4 +89,4 @@ In Fern Docs, this will look like:
 </CodeBlock>
 
 In Fern Docs, this will look like: 
-![property deprecated](https://fern-image-hosting.s3.amazonaws.com/property-deprecated.png)
+![property deprecated](https://fern-image-hosting.s3.amazonaws.com/property-deprecated.png)

fern/docs/pages/overview/define-your-api/openapi/extensions.mdx

@@ -266,7 +266,7 @@ export interface Person  { # <---- Overridden name
 }
 ```
 
-## Parameter Names 
+## Parameter names 
 
 The `x-fern-parameter-name` extension allows you to customize the variable name of OpenAPI 
 parameters. 
@@ -458,7 +458,7 @@ and sent as `false` for the non-streaming variant. Additionally, a stream of the
 is returned in the streaming variant, whereas the `Logs` array is returned in the non-streaming
 variant.
 
-## Ignoring Schemas or endpoints
+## Ignoring schemas or endpoints
 
 If you want Fern to skip reading any endpoint or schemas, you can use the 
 `x-fern-ignore` extension. 
@@ -543,7 +543,7 @@ shown in the third tab.
     </CodeBlock>
 </CodeBlocks>
 
-## Request + Response Examples
+## Request + response examples
 
 While OpenAPI has several fields for examples, there is no easy way 
 to associate a request with a response. This is expecially useful when 
@@ -580,7 +580,7 @@ components:
           type: integer
 ```
 
-### Code Samples
+### Code samples
 
 If you'd like to specify custom code samples for your example, 
 use `code-samples`. 
@@ -605,6 +605,29 @@ paths:
 ```
 
 If you're on the Fern Starter plan for SDKs you won't 
-have to worry about manually adding code samples! Our generators will do that for you. 
+have to worry about manually adding code samples! Our generators will do that for you.
+
+### Availability
+
+The `x-fern-availability` extension is used to mark the availability of an endpoint. The availability information propagates into the generated Fern Docs website as visual tags. 
+
+The options are: 
+- `beta`
+- `generally-available`
+- `deprecated`
+
+The example below marks that the `POST /pet` endpoint is `deprecated`.
+
+<CodeBlock title="openapi.yml">
+```yaml
+paths:
+  /pet:
+    post:
+      x-fern-availability: deprecated <---- 
+      ...
+```
+</CodeBlock>
+
+### Request new extensions
 
 If there's an extension you want that doesn't already exist, file an [issue](https://github.com/fern-api/fern/issues/new) to start a discussion about it.