Content updates

app/globals.css

@@ -106,3 +106,12 @@ strong {
     cursor: pointer;
   }
 }
+
+table {
+  width: 100%;
+}
+
+td {
+  padding: 0.5rem !important;
+
+}

content/docs/YakShaver/yakshaver-tips.mdx

@@ -10,55 +10,141 @@ date: '2025-01-28T13:00:00.000Z'
 
 Here are some tips to creating the perfect Work Item:
 
+
 ## When recording
 
 ### 1. State your intent
 
 Begin the recording with the purpose.
 
-> *“Send an email task to...”*
-> *“I have a new feature request for SugarLearning...”*
+> *“Send an email task to...”*  
+> *“I have a new feature request for the Northwind Project...”*
+
+**✅ Good Example:**
+>
+> “Create a new bug report for the login page in the Northwind project. The issue is users can’t reset their password. (...)”
+
+**❌ Bad Example:**
+>
+> “This is broken.”
+
+Be as specific as possible so the AI knows what action to take and what project you are refering to. 
+
+
+**Pro Tip:** A good practice is to end your video by restating your intent and the project name. This reinforces your request and helps the AI generate an accurate Work Item.
+
+---
+
+## 2. Give context
 
-### 2. Give context
+If you're seeing a section you should refer to the section's heading.
 
-If you're seeing a section you should refer to the section's heading
+**Note:** Have a look at these [best practices](/docs/giving-context)
 
-**Note:**  Have a look at these [best practices](/docs/giving-context)
+**✅ Good Example:**
+>
+> “On the dashboard, under the ‘Reports’ section, the export button is missing.”
 
-### 3. Detail bug reports
+**❌ Bad Example:**
+>
+> “It’s not working here.”
+
+---
+
+## 3. Detail bug reports
 
 For bugs, mention reproduction steps and expected behaviour.
 
 > *“First do this, then do this, then this error occurs, but I expect it to do this”*
 
 **Note:** Have a look at [drafting your bug with enough details](https://www.ssw.com.au/rules/report-bugs-and-suggestions/#tip-1-draft-your-bug-with-enough-details)
 
-### 4. Mention additional team members
+**✅ Good Example:**
+>
+> “Step 1: Go to the login page. Step 2: Enter your email and click ‘Forgot Password’. Step 3: No email is sent. I expect to receive a password reset email.”
+
+**❌ Bad Example:**
+>
+> “Reset password doesn’t work.”
+
+---
+
+## 4. Mention additional team members
 
 So you include others who are not in the meeting.
 
 > *“...Cc Adam and Uly”*
 
 **Note:** Creating a PBI or bug report will automatically CC the Product Owner and Tech Lead. [Why?](/docs/user-mention-guidelines-in-work-item-descriptions)
 
-### 5. Collaborative effort goes a long way
+**✅ Good Example:**
+>
+> “Please CC @adam and @uly on this item as they need to review the changes.”
+
+**❌ Bad Example:**
+>
+> “Let someone else know.”
+
+---
+
+## 5. Collaborative effort goes a long way
+
+Invite a colleague when recording to allow for multiple perspectives and explanations, allowing for increased clarity and quality of the work item.
 
-Invite a colleague when recording to allow for multiple perspectives and explanations, allowing for increased clarity and quality of the work item.![](/tinacloud-two-people-yakshave.png)
+![](/tinacloud-two-people-yakshave.png)
 
 **Figure: 2 or more people in a YakShave is always better**
 
-## After recording
+**Tip:** If possible, have another team member present to clarify requirements or add missing details during the recording.
+
+---
+
+
+## Common Mistakes to Avoid
+
+Avoid these common pitfalls to ensure YakShaver produces the best results:
+
+- **Being too vague:** Not stating what you want the AI to do.
+  - _Example: “This needs fixing.” (What needs fixing? Where?)_
+- **Missing context:** Not mentioning which page, feature, or user role is affected.
+- **Skipping steps:** Not describing how to reproduce a bug or what the expected outcome is.
+- **Not mentioning key people:** Forgetting to CC or mention stakeholders who need to be involved.
+- **Recording in a noisy environment:** Background noise can make it hard for the AI to understand your intent.
 
-### 1. Move PBIs (if needed)
+Take a moment to review your recording and make sure you’ve avoided these mistakes before submitting.
 
-If the PBI wasn’t created in the correct project, use the “Move PBI” option to relocate it to the right project.
+---
+
+## Sample Video Script
+
+Here’s an example script for a YakShaver recording that follows best practices.
+
+This script clearly states the intent, provides context, details the bug, mentions key people, and demonstrates collaboration.
+
+```text
+Hi team, I’d like to create a new bug report for the login page on the project Northwind. 
+When users try to reset their password, no email is sent.  
 
-### 2. Review and like the Work Item
+This is how it happened, I went to the login page and entered my email address. Then I clicked on ‘Forgot Password’.  
 
-Check the PBI title and content. If everything looks good, [react with a 👍 to show you’ve reviewed it](https://www.ssw.com.au/rules/react-to-reviewed-pbis).
+After 5 minutes monitoring my email inbox I still haven't received my password reset email.  
+
+Please CC @adam and @uly as they need to review this.  
+```
+
+
+---
 
-**Note:** You should also do this after checking Work Items created by others.
+## Quick Reference: Do’s and Don’ts
 
-### 3. Loop in more people
+Refer to this table before recording to maximize the quality of your YakShaver Work Items!
 
-If someone needs to join the conversation later, add "(looping @username)" at the top of the Work Item description.
+| ✅ Do’s | ❌ Don’ts |
+|-------------------------------|-------------------------------|
+| Clearly state your intent      | Be vague or ambiguous         |
+| Give specific context (page, feature, etc.) | Assume the AI knows what you mean |
+| List steps to reproduce bugs   | Skip important details        |
+| Mention/CC relevant team members | Forget to involve stakeholders |
+| Record in a quiet environment  | Record with lots of background noise |
+| Collaborate with others when possible | Work in isolation if clarity is needed |
+

content/docsTableOfContents/YakShaver/toc.mdx

@@ -52,9 +52,6 @@ parentNavigationGroup:
         _template: item
   - title: Best Practices
     items:
-      - title: Specify the project backlog you want
-        slug: content/docs/YakShaver/specify-the-project.mdx
-        _template: item
       - title: Giving Context
         slug: content/docs/YakShaver/giving-context.mdx
         _template: item
@@ -88,4 +85,3 @@ parentNavigationGroup:
         slug: content/docs/YakShaver/support.mdx
         _template: item
 ---
-