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 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/docs/YakShaver/yakshaver-tips.mdx b/content/docs/YakShaver/yakshaver-tips.mdx index 954321413..72fd8c972 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.” + +--- + +## 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 | + 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 --- -