From 7a37f3cf7a8262248bf9e3e67ee261d591010ec1 Mon Sep 17 00:00:00 2001 From: Tom Iwainski Date: Thu, 11 Dec 2025 10:09:08 +1100 Subject: [PATCH 1/4] Remove 'Specify the Project' YakShaver doc Deleted the 'Specify the Project Backlog You Want' documentation and its reference from the YakShaver table of contents. This streamlines the docs by removing outdated or unnecessary content. --- content/docs/YakShaver/specify-the-project.mdx | 14 -------------- content/docsTableOfContents/YakShaver/toc.mdx | 4 ---- 2 files changed, 18 deletions(-) delete mode 100644 content/docs/YakShaver/specify-the-project.mdx diff --git a/content/docs/YakShaver/specify-the-project.mdx b/content/docs/YakShaver/specify-the-project.mdx deleted file mode 100644 index 67916d001..000000000 --- a/content/docs/YakShaver/specify-the-project.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -seo: - title: Specify the Project Backlog You Want -title: Specify the Project Backlog You Want -date: '2025-07-23T14:00:00.000Z' ---- - -When YakShaver doesn't know which project to target, it asks the user which slows down the process. The best way to avoid this is verbally mentioning the target project (YakShaver does not read your screen). - -We recommended verbally specifying the project when you begin the Shave. - -`"Please create a work item in the Northwind project"` - -`"I have noticed a problem on the YakShaver website"` diff --git a/content/docsTableOfContents/YakShaver/toc.mdx b/content/docsTableOfContents/YakShaver/toc.mdx index 41ff538a7..ca993794e 100644 --- a/content/docsTableOfContents/YakShaver/toc.mdx +++ b/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 --- - From bc99f4cc61a716b056507d8108f0a7a3ddc711cb Mon Sep 17 00:00:00 2001 From: Tom Iwainski Date: Thu, 11 Dec 2025 12:39:03 +1100 Subject: [PATCH 2/4] Add table and cell styling to globals.css Set tables to full width and add padding to table cells for improved layout and readability. --- app/globals.css | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/app/globals.css b/app/globals.css index fb2aa53e7..ede7966dc 100644 --- a/app/globals.css +++ b/app/globals.css @@ -106,3 +106,12 @@ strong { cursor: pointer; } } + +table { + width: 100%; +} + +td { + padding: 0.5rem !important; + +} \ No newline at end of file From 9e5a9f40b82502de08b8bf0ddeafb6ebab1955fb Mon Sep 17 00:00:00 2001 From: Tom Iwainski Date: Thu, 11 Dec 2025 12:39:16 +1100 Subject: [PATCH 3/4] Expand and improve YakShaver tips documentation Enhanced the YakShaver tips with clearer examples, pro tips, and a sample video script. Added sections on common mistakes, a quick reference table of do's and don'ts, and improved guidance for providing context, detailing bugs, and collaborating. These changes aim to help users create higher quality Work Items and avoid common pitfalls. --- content/docs/YakShaver/yakshaver-tips.mdx | 120 +++++++++++++++++++--- 1 file changed, 103 insertions(+), 17 deletions(-) diff --git a/content/docs/YakShaver/yakshaver-tips.mdx b/content/docs/YakShaver/yakshaver-tips.mdx index 954321413..d88ca657a 100644 --- a/content/docs/YakShaver/yakshaver-tips.mdx +++ b/content/docs/YakShaver/yakshaver-tips.mdx @@ -10,22 +10,48 @@ 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. @@ -33,7 +59,17 @@ For bugs, mention reproduction steps and expected behaviour. **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. @@ -41,24 +77,74 @@ So you include others who are not in the meeting. **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.” -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) +--- + +## 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. + +![](/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. -### 1. Move PBIs (if needed) +--- -If the PBI wasn’t created in the correct project, use the “Move PBI” option to relocate it to the right project. -### 2. Review and like the Work Item +## Common Mistakes to Avoid -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). +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. + +Take a moment to review your recording and make sure you’ve avoided these mistakes before submitting. + +--- + +## Sample Video Script + +Here’s an example script for a YakShaver recording that follows best practices: + +``` +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. + +This is how it happened, I went to the login page and entered my email address. Then I clicked on ‘Forgot Password’. + +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. + +``` + +This script clearly states the intent, provides context, details the bug, mentions key people, and demonstrates collaboration. + + +--- -**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 | + From f28bed72da9ba3cad4e7d0bc6ddc14a7d0bd7d54 Mon Sep 17 00:00:00 2001 From: Tom Iwainski Date: Thu, 11 Dec 2025 12:45:46 +1100 Subject: [PATCH 4/4] Improve sample video script formatting and clarity Moved the explanation of the sample script above the code block and clarified its purpose. Changed the code block language to 'text' for better readability and adjusted formatting for consistency. --- content/docs/YakShaver/yakshaver-tips.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/content/docs/YakShaver/yakshaver-tips.mdx b/content/docs/YakShaver/yakshaver-tips.mdx index d88ca657a..72fd8c972 100644 --- a/content/docs/YakShaver/yakshaver-tips.mdx +++ b/content/docs/YakShaver/yakshaver-tips.mdx @@ -117,20 +117,20 @@ Take a moment to review your recording and make sure you’ve avoided these mist ## Sample Video Script -Here’s an example script for a YakShaver recording that follows best practices: +Here’s an example script for a YakShaver recording that follows best practices. -``` -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. - -This is how it happened, I went to the login page and entered my email address. Then I clicked on ‘Forgot Password’. +This script clearly states the intent, provides context, details the bug, mentions key people, and demonstrates collaboration. -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. - -``` +```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. -This script clearly states the intent, provides context, details the bug, mentions key people, and demonstrates collaboration. +This is how it happened, I went to the login page and entered my email address. Then I clicked on ‘Forgot Password’. + +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. +``` ---