Clarify how product and version switchers work together (#218)

Author: devalog

fern/products/docs/pages/navigation/products.mdx

@@ -32,15 +32,15 @@ Each product can contain its own distinct versions, tabs, sections, pages, and A
 Create a `products` folder inside of your `fern` folder. To specify a product's contents and navigational structure, add a `.yml` file to the `products` folder for each product.
 Make sure to include the `navigation` and `tabs` properties, if applicable.
 
-```bash
+```bash {4, 7-8}
 fern/
   ├─ fern.config.json
   ├─ generators.yml
-  ├─ docs.yml
+  ├─ docs.yml # Site-level contents and navigation
   └─ products/
     ├─ ...
-    ├─ product-a.yml
-    └─ product-b.yml
+    ├─ product-a.yml # Contents and navigation for Product A
+    └─ product-b.yml # Contents and navigation for Product B
 ```
 
 <CodeBlocks>
@@ -92,10 +92,34 @@ The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions`
 
 <Note>If you provide both an `image` and an `icon`, the `image` will take precedence.</Note>
 
-<Accordion title='Setting up Versioned Products'>
-  Products can be versioned or unversioned. The following is an example of how more complex products might be organized:
+The below example is a `docs.yml` configuration for a site with two products, Product A and Product B.
 
-  ```bash
+<CodeBlock title="docs.yml">
+```yaml {2-3, 8-9}
+products:
+  - display-name: Product A
+    path: ./products/product-a.yml
+    icon: fa-solid fa-leaf # optional
+    slug: product-a # optional
+    subtitle: Product A subtitle # optional
+
+  - display-name: Product B
+    path: ./products/product-b/latest.yml # <-- default showing latest
+    image: ./images/product-b.png # optional
+    slug: product-b # optional
+    subtitle: Product B subtitle # optional
+```
+</CodeBlock>
+
+### Add versioning to your products (optional)
+
+You can optionally add versions to a product. Versioned and unversioned products can live next to each other in your site. Each version of a single product has its own `yml` file.
+
+In the below example, Product A is **unversioned** and Product B is **versioned**:
+
+<CodeBlock>
+
+  ```bash {8, 10-17}
   fern/
     ├─ fern.config.json
     ├─ generators.yml
@@ -104,35 +128,30 @@ The optional parameters are: `image`, `icon`, `subtitle`, `slug`, and `versions`
       ├─ ...
     └─ products/
       ├── product-a.yml # basic unversioned product
-      ├── product-b/ # unversioned product with product-specific pages
-      │   ├─ pages/...
-      │   └─ product-with-pages.yml
-      └── product-c/ # versioned product
-          ├─ product-c.yml
+      └── product-b/ # versioned product
+          ├─ product-b.yml
           └─ versions/
-            ├─ v1/
-            │  ├─ v1.yml
+            ├─ latest/
+            │  ├─ latest.yml
             │  └─ pages/...
             └─ v2/
               ├─ v2.yml
               └─ pages/...
   ```
+</CodeBlock>
 
-  For more information on setting up versions, follow our [versioning docs](/learn/docs/building-and-customizing-your-docs/versioning).
-</Accordion>
-
-
+The top-level `doc.yml` configuration for a Fern Docs website containing two products, one unversioned and one versioned, might look something like this:
 
 <CodeBlock title="docs.yml">
-```yaml
+```yaml {2, 8, 13-17}
 products:
-  - display-name: Product A
+  - display-name: Product A # unversioned
     path: ./products/product-a.yml
     icon: fa-solid fa-leaf # optional
     slug: product-a # optional
     subtitle: Product A subtitle # optional
 
-  - display-name: Product B
+  - display-name: Product B # versioned
     path: ./products/product-b/latest.yml # <-- default showing latest
     image: ./images/product-b.png # optional
     slug: product-b # optional
@@ -145,6 +164,8 @@ products:
 ```
 </CodeBlock>
 
+For more information on setting up versioned products, follow our [versioning docs](/docs/navigation/versions).
+
 ### Remove extra `navigation` from `docs.yml`
 If your `docs.yml` file includes a `navigation` field or a `tabs` field, be sure to remove. Those fields should now belong in the product-specific `.yml` files. 
 </Steps>

fern/products/docs/pages/navigation/versions.mdx

@@ -14,9 +14,10 @@ Each version of your docs can contain its own distinct tabs, sections, pages, an
 <Steps>
 ### Define your versions
 
-Create a `versions` folder inside of your `fern` folder. TO specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable. 
+Create a `versions` folder inside of your `fern` folder. To specify the contents of each version, add a `.yml` file to the `versions` folder to define the navigational structure of that version. Make sure to include the `navigation` and `tabs` properties, if applicable. 
 
-```bash
+<CodeBlock>
+```bash {7-11}
 fern/
   ├─ fern.config.json
   ├─ generators.yml
@@ -29,6 +30,10 @@ fern/
     ├─ v2-2/pages/...
     └─ v2-2.yml
 ```
+</CodeBlock>
+
+
+Version-specific `yml` files:
 
 <CodeBlocks>
 <CodeBlock title="versions/v2-1.yml">
@@ -73,6 +78,8 @@ tabs:
 </CodeBlock>
 </CodeBlocks>
 
+<Note>You can also have multiple products, some versioned and some unversioned. For more information on setting up multiple products, follow our [product switching docs](/docs/navigation/products).</Note>
+
 ### Add your version configuration
 
 To define a version, in `docs.yml`, add an item to the `versions` list, specifying the `display-name` and `path`.