update examples page (#879)

Author: ethanpalm

components/examples.mdx

@@ -1,21 +1,27 @@
 ---
 title: "Examples"
-description: "Display code blocks at the top-right of the page on desktop devices"
+description: "Display code blocks in the right sidebar on desktop devices"
 icon: 'between-horizontal-start'
 ---
 
-The `<RequestExample>` and `<ResponseExample>` stick code blocks to the top-right of a page even as you scroll. The components work on all pages even if you don't use an API playground.
+The `<RequestExample>` and `<ResponseExample>` components display code blocks in the right sidebar to create a two-column layout that keeps examples visible while users scroll through your content. These components are designed for API documentation, but they work on all pages.
 
-`<RequestExample>` and `<ResponseExample>` show up like regular code blocks on mobile.
+Common use cases:
 
-## Request Example
+- API endpoint documentation with request and response examples
+- Configuration examples alongside explanatory text
+- Code samples that users reference while following instructions
+- Before and after examples in tutorials
 
-The `<RequestExample>` component works similar to [CodeGroup](/components/code-groups), but displays the request content on the right sidebar. Thus, you can put multiple code blocks inside `<RequestExample>`.
+On mobile devices, `<RequestExample>` and `<ResponseExample>` components display as regular code blocks and can be scrolled past.
 
-Please set a name on every code block you put inside RequestExample.
+## RequestExample
 
-<RequestExample>
-````mdx RequestExample Example
+Use `<RequestExample>` to pins code examples in the right sidebar. This component works similarly to the [CodeGroup](/components/code-groups) component, but displays the code in the sidebar instead of inline.
+
+You can include multiple code blocks inside a single `<RequestExample>`. Each code block must have a title attribute.
+
+````mdx RequestExample
 <RequestExample>
 
 ```bash Request
@@ -25,14 +31,12 @@ Please set a name on every code block you put inside RequestExample.
 
 </RequestExample>
 ````
-</RequestExample>
 
-## Response Example
+## ResponseExample
 
-The `<ResponseExample>` component is the same as `<RequestExample>` but will show up underneath it.
+The `<ResponseExample>` component pins code examples in the right sidebar beneath any `<RequestExample>` content on the same page.
 
-<ResponseExample>
-````mdx ResponseExample Example
+````mdx ResponseExample
 <ResponseExample>
 
 ```json Response
@@ -41,4 +45,3 @@ The `<ResponseExample>` component is the same as `<RequestExample>` but will sho
 
 </ResponseExample>
 ````
-</ResponseExample>