Making the exercise links and instructions clearer

Author: erikhatcher

docs/10_About_workshop/1_intro.mdx

@@ -13,9 +13,7 @@ There are two tools in the Playground:
   * `Search Demo Builder`: a configurable search UI on your data
 
 The exercises will only use the Code Sandbox, as it allows saving and sharing links to
-the full environment and allows us to work on one topic at a time.
-
-We'll cover the Search Demo Builder briefly near the end of the workshop.
+the full environment.  Note that there are several templates in the Code Sandbox with more elaborate example data, configurations, and queries than the exercises in this workshop; we use simpler playgrounds here so that we can focus on one aspect at time.
 
 ## Code Sandbox layout
 
@@ -38,11 +36,11 @@ The DATA SOURCE pane also accepts the comment prefix.
 
 ### Error messages
 
-Sometimes aren't related to the actual cause. Syntax errors can cause confusion in interpreting the pipeline, configuration, or data.
+Sometimes error messages aren't related to the actual cause. Syntax errors can cause confusion in interpreting the pipeline, configuration, or data.
 
 Step back with a leaner, cleaner working example and build back up carefully.
 
-This is why a Playground is useful - mistakes andtypos happen. syntax is unforgiving.
+This is why a Playground is useful - mistakes and typos happen. The syntax is unforgiving.
 Error messages are our friend, giving us an opportunity to fix and learn iteratively in a safe environment.
 
 ## Resources

docs/10_About_workshop/8_Exercises/1_.mdx

@@ -1,19 +1,25 @@
-# Exercise: Fix me
+# Intro group exercise
 
 Here's a gentle first exercise to get us started with the playground.
-You'll see an index configuration and an aggregation pipeline stage that
-hasn't been introduced yet, but no worries - 
-we'll get there next. See if you can solve it with what you already know or expect.
 
 We're going to work through this one together as a group.
 
-1. Navigate to the Playground snapshot linked below.
+1. Navigate to the `🔗 Playground link`.
 2. Press "Run"
 3. Notice the empty array `[]` of results
 
+All exercises in this workshop will be in this format, with a `🔗 Playground link`, followed
+
+## 🤔 Exercise: Fix me
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/6782aea0667feaaf06324b87">🔗 Playground link: Exercise: Fix me</Playground>
+
+You'll see an index configuration and an aggregation pipeline stage that
+hasn't been introduced yet, but no worries -  we'll get there next. See if you can solve it with
+what you already know or expect.
+
 The objective with this exercise is to adjust the `FIX_ME` in the `$search` aggregation pipeline stage so that the document (in the Data Source pane) matches the query and appears in the Results pane.
 
-* <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/6782aea0667feaaf06324b87">Playground: Fix me</Playground>
 
   [![Playground intro exercise](/img/playground_intro_exercise.png)](/img/playground_intro_exercise.png)
 
@@ -38,7 +44,7 @@ The objective with this exercise is to adjust the `FIX_ME` in the `$search` aggr
   </details>
 
   <details>
-  <summary>There are other possible solutions too, such as:</summary>
+  <summary>There are other possible solutions too, such as...</summary>
   <div>
   `atlas` or `fundamentals` or other case variations of any `title` field words
   </div>

docs/10_About_workshop/8_Exercises/2_.mdx

@@ -1,6 +1,6 @@
-# Exercise: My very first playground
+# Your own playground
 
-Create a <Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/new">new playground</Playground>.
+Create a <Playground url="https://search-playground.mongodb.com/tools/code-sandbox/snapshots/new">🔗 Playground link: new playground</Playground>.
 
 Clear the data box in the lower left (select-all, delete), and then type, paste, or import an array of a few documents. You could copy/paste the below, for example:
 

docs/30_Index_configuration/8_Exercises/1_.mdx

@@ -1,94 +1,134 @@
 # Exercises: Basic types
 
-## boolean
+These exercises demonstrate how Atlas Search handles the basic data types of boolean, date, number, and ObjectId. Each exercise isolates a specific data type and search operator.
+
+## boolean: equals
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1d80e97570c2714a07e0">🔗 Playground link: `equals`</Playground> 
+
+The documents contain a boolean field, and the query is looking for documents with a value of `true`.
+Fix the incorrect field name in the query.
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1d80e97570c2714a07e0">`equals`</Playground> 
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     path: "in_stock"
     ```
 
-    <Playground url="https://search-playground.mongodb.com/tools/code-playground/snapshots/669e6ab1d49ef6fad98118b4">boolean `equals` fixed</Playground>
+    🔗 <Playground url="https://search-playground.mongodb.com/tools/code-playground/snapshots/669e6ab1d49ef6fad98118b4">boolean `equals` fixed</Playground>
   </div>
 </details>
 
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1e53d0df60f0254e5d2b">`in`</Playground>
+## boolean: in
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1e53d0df60f0254e5d2b">🔗 Playground link: `in`</Playground>
+
+What values are allowed in an `in` clause for a `boolean` field?  
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     value: [true, false]
     ```
 
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c19c4e97570c2714a07dc">boolean `in` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c19c4e97570c2714a07dc">boolean `in` fixed</Playground>
   </div>
 </details>
 
 
-## date
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1b0fe97570c2714a07de">`equals`</Playground>
+## date: equals
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1b0fe97570c2714a07de">🔗 Playground link: `equals`</Playground>
+
+Dates require BSON syntax.
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     value: ISODate("2023-11-01T00:00:00.000Z")
     ```
 
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c20a4d0df60f0254e5d2d">date `equals` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c20a4d0df60f0254e5d2d">date `equals` fixed</Playground>
   </div>
 </details>
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1b5fd0df60f0254e5d27">`in`</Playground>
+## date: in
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c1b5fd0df60f0254e5d27">🔗 Playground link: `in`</Playground>
+
+BSON date syntax is needed.
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     value: [ISODate("2024-02-01T00:00:00.000Z"), ISODate("2023-11-01T00:00:00.000Z"), ISODate("2007-12-25T00:00:00.000Z")]
     ```
 
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c210ee97570c2714a07e2">date `in` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c210ee97570c2714a07e2">date `in` fixed</Playground>
   </div>
 </details>
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c21c8d0df60f0254e5d2f">`range`</Playground>
+## date: range
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c21c8d0df60f0254e5d2f">🔗 Playground link: `range`</Playground>
+
+What's the correct field name?
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     path: "published_date"
     ```
-    <Playground url="https://search-playground.mongodb.com/tools/code-playground/snapshots/669e6b18d49ef6fad98118b6">date `range` fixed</Playground>
+    🔗 <Playground url="https://search-playground.mongodb.com/tools/code-playground/snapshots/669e6b18d49ef6fad98118b6">date `range` fixed</Playground>
   </div>
 </details>
 
 
-## number
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c25abd0df60f0254e5d35">`equals`</Playground>
+## number: equals
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c25abd0df60f0254e5d35">🔗 Playground link: `equals`</Playground>
+
+What's the correct field name?
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     path: "price"
     ```
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c25e2d0df60f0254e5d37">number `equals` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c25e2d0df60f0254e5d37">number `equals` fixed</Playground>
   </div>
 </details>
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c252ce97570c2714a07e6">`in`</Playground>
+## number: in
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c252ce97570c2714a07e6">🔗 Playground link: `in`</Playground>
+
+What numeric value can be used to match one of the documents?
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     value: [19.99, 37.5]
     ```
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c2569d0df60f0254e5d33">number `in` fixed</Playground>
+   🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c2569d0df60f0254e5d33">number `in` fixed</Playground>
   </div>
 </details>
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c2313d0df60f0254e5d31">`range`</Playground> (fix two issues, not just one!)
+## number: range
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c2313d0df60f0254e5d31">🔗 Playground link:  `range`</Playground>
+
+There are *two* issues to fix in this exercises. What's the correct field name? And what's wrong with 
+the one of the range values?
+
 <details>
   <summary>Solution</summary>
   <div>
@@ -99,29 +139,38 @@
       lte: 25.00
     }
     ```
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c22bde97570c2714a07e4">number `range` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c22bde97570c2714a07e4">number `range` fixed</Playground>
   </div>
 </details>
 
-## ObjectId
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c265dd0df60f0254e5d39">`equals`</Playground>
+## ObjectId: equals
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c265dd0df60f0254e5d39">🔗 Playground link: `equals`</Playground>
+
+ObjectId requires BSON syntax. Copy and paste is your friend here.
+
 <details>
   <summary>Solution</summary>
   <div>
     ```js
     value: ObjectId("5a9427648b0beebeb69589a1")
     ```
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962d77aa132ffc76719f53">ObjectId `equals` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962d77aa132ffc76719f53">ObjectId `equals` fixed</Playground>
   </div>
 </details>
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c26d5d0df60f0254e5d3b">`in`</Playground>
+## ObjectId: in
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c26d5d0df60f0254e5d3b">🔗 Playground link:  `in`</Playground>
+
+What value can be placed in the `in` array to match the document?
+
 <details>
   <summary>Solution</summary>
   <div>
      ```js
      value: [ObjectId("ba94c7648b0beebeb69589a1"), ObjectId("5a9427648b0beebeb69589a1")]
      ```
-     <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c270cd0df60f0254e5d3d">ObjectId `in` fixed</Playground>
+     🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c270cd0df60f0254e5d3d">ObjectId `in` fixed</Playground>
   </div>
 </details>

docs/30_Index_configuration/8_Exercises/2_.mdx

@@ -1,12 +1,13 @@
 # Exercises: Type mismatches
 
-Atlas Search is quite type sensitive. The BSON type of each field is used to determine which index mapping type to use. And at query time, the search operator type of `value` is used to determine which index to query for a particular field/path name.
+Atlas Search is quite type sensitive. The BSON type of each field is used to determine which index mapping type to use. And at query time, the search operator type of the `value` is used to determine which indexed type to query for a particular field/path name.
 
 ## boolean
+
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dfdaa132ffc76719f57">🔗 Playground link: boolean type mismatch</Playground>
+
 Why doesn't this playground match as expected?
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dfdaa132ffc76719f57">boolean type mismatch</Playground>
-  
 <details>
 <summary>Explanation</summary>
 <div>
@@ -30,7 +31,10 @@ Here's a corrected pipeline:
 </details>
 
 ## number
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962e2faa132ffc76719f5b">number type mismatch</Playground>
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962e2faa132ffc76719f5b">🔗 Playground link: number type mismatch</Playground>
+
+Why won't the query match?
+
 <details>
   <summary>Solution</summary>
   <div>
@@ -44,7 +48,10 @@ Here's a corrected pipeline:
 
 
 ## ObjectID
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dc7aa132ffc76719f55">ObjectId type mismatch</Playground>
+<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/67962dc7aa132ffc76719f55">🔗 Playground link: ObjectId type mismatch</Playground>
+
+The ObjectId value is correct, but the document does not match. Can you spot, and fix, the issue?
+
 <details>
   <summary>Solution</summary>
   <div>

docs/30_Index_configuration/8_Exercises/3_.mdx

@@ -4,7 +4,10 @@ Refer back to the `string` section above for details on configuring the `token`
 
 ## `equals` on strings
 
-<Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c2fedd0df60f0254e5d3f">`equals` on `string` mismatch</Playground>
+🔗 Playground link:  <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c2fedd0df60f0254e5d3f">`equals` on `string` mismatch</Playground>
+
+The category field is a string. Try using the `string` field type - why doesn't it work?  What's the right type to use in order to use the `equals` operator?
+
 <details>
   <summary>Solution</summary>
   <div>
@@ -24,7 +27,7 @@ Refer back to the `string` section above for details on configuring the `token`
       }
     }
     ```
-    <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c3028d0df60f0254e5d41">token type `equals` fixed</Playground>
+    🔗 <Playground url="https://search-playground.corp.mongodb.com/tools/code-sandbox/snapshots/679c3028d0df60f0254e5d41">token type `equals` fixed</Playground>
   </div>
 </details>
 

docs/welcome.mdx

@@ -6,40 +6,31 @@ sidebar_position: 1
 
 This workshop presents the fundamental concepts of the full-text search capabilities provided by Atlas Search, and empowers developers with best practice techniques to bring powerful search experiences to their applications. Developers will engage with a number of practical exercises to gain experience and confidence in understanding textual analysis and tokenization, configuring field types, and leveraging search operators for better relevancy.
 
-## What You'll Learn
+## What you'll Learn
 
 1. **Atlas Search overview**
- - System architecture
- - Index configuration
- - Inverted index
+   - System architecture
+   - Index configuration
+   - Inverted index
 
 2. **Analysis**
-  - Built-in analyzers
-  - Multi analysis
+    - Built-in analyzers
+    - Multi analysis
 
 3. **Search operators**
-  - Text operators
-  - Query construction
+    - Text operators
+    - Query construction
 
 4. **Relevancy**
-  - Scoring
-  - TF/IDF and BM25
+    - Scoring
+    - TF/IDF and BM25
 
 5. **Data modeling and schema design for Atlas Search**
-  - Best practices
+    - Best practices
 
-## TODO
-
-Fill in any other blanks for welcoming and setting the stage for the workshop.
-
-## The Exercises
+## What you'll need
 
 This workshop uses the Atlas Search Playground for the exercises.
 All you need is a browser and network connectivity.
 This handy developer tool allows us to work in an isolated, focused environment
 with no setup.
-
-
-🙋🏾‍♀️
-
-📣