Merge branch 'SSWConsulting:main' into main

SSWConsulting · Oct 31, 2023 · 7d0f233 · 7d0f233
2 parents 7f1095f + c8913db
commit 7d0f233
Show file tree

Hide file tree

Showing 19 changed files with 148 additions and 176 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,22 +1,21 @@
-<!--- Thanks for contributing to SSW.Rules! -->
-## Reason for change (Issue, Email, conversation + reason, etc)
-<!-- 
-- Example 1 - Relates to #{{ ISSUE NUMBER }}
-- Example 2 - As per my conversation with...
-- Example 3 - Based on email thread, subject...
-- Example 4 - I noticed that... 
--->
-{{ REASON FOR CHANGE - WHAT WAS THE TRIGGER FOR THIS CHANGE }}
 
-{{ SUMMARY OF CHANGES }}
+> 1. What triggered this change? (PBI link, Email Subject, conversation + reason, etc)
 
-<!-- 
-Have you seen our Rules to Better Pull Requests?
-https://www.ssw.com.au/rules/rules-to-better-pull-requests/
+✏️
+
+> 2. What was changed?
 
-Please provide a good title and a short description of your pull request
-See https://www.ssw.com.au/rules/write-a-good-pull-request/ for further guidance
+✏️
 
-Did you do an over the shoulder review?
-https://www.ssw.com.au/rules/over-the-shoulder-prs 
--->
+> 3. Did you do pair or mob programming?
+
+✏️
+<!-- E.g. I worked with @gordonbeeming and @sethdailyssw -->
+
+<!-- 
+Check out the relevant rules
+- https://www.ssw.com.au/rules/rules-to-better-pull-requests
+- https://www.ssw.com.au/rules/write-a-good-pull-request
+- https://www.ssw.com.au/rules/over-the-shoulder-prs 
+- https://www.ssw.com.au/rules/do-you-use-co-creation-patterns
+-->
diff --git a/categories/artificial-intelligence/rules-to-better-gpt.md b/categories/artificial-intelligence/rules-to-better-gpt.md
@@ -3,6 +3,7 @@ type: category
 title: Rules to Better GPT
 guid: 9e0c432c-4925-4075-a824-5230e0e71354
 uri: rules-to-better-gpt
+consulting: https://www.ssw.com.au/consulting/artificial-intelligence
 index:
 - what-is-chatgpt
 - chatgpt-skills-weaknesses

diff --git a/categories/software-development/rules-to-better-testing.md b/categories/software-development/rules-to-better-testing.md
@@ -28,6 +28,6 @@ index:
 ---
 
 `youtube: https://www.youtube.com/watch?v=W-KToHWJ4zY`  
-**Video: Chewing the Fat Review - Testing with Luke Cook and Piers Sinclair**
+**Video: Chewing the Fat Review - Testing with Luke Cook and Piers Sinclair (7 min)**
 
-Check out the extended cut - https://www.youtube.com/watch?v=PHrj1GxQp7I
+[Watch the extended cut](https://www.youtube.com/watch?v=PHrj1GxQp7I) (32 min).
diff --git a/rules/azure-naming-resource-groups/rg-good.png b/rules/azure-naming-resource-groups/rg-good.png
diff --git a/rules/azure-naming-resource-groups/rule.md b/rules/azure-naming-resource-groups/rule.md
@@ -41,15 +41,15 @@ There are no cost benefits in consolidating Resource Groups, so use them! Have a
 You should keep all a product's resources within the same Resource Group. Your developers can then find all associated resources quickly and easily, and helps minimize the risk of duplicate resources being created. It should be clear what resources are being used in the Dev environment vs. the Production environment, and Resource Groups are the best way to manage this.
 
 ::: bad
-![Bad Example - A rogue dev resource in the Production RG](rogue-resource.png)
+![Bad example - A rogue dev resource in the Production RG](rogue-resource.png)
 :::
 
 ### Don't mix environments
 
 There's nothing worse than opening up a Resource Group and finding several instances of the same resources, with no idea what resources are in dev/staging/production. Similarly, if you find a single instance of a Notification Hub, how do you know if it's being built in the test environment, or a legacy resource needed in production?
 
 ::: bad
-![Bad Example - Staging and Prod resources in the same RG](bad-azure-environments.png)
+![Bad example - Staging and Prod resources in the same RG](bad-azure-environments.png)
 :::
 
 ### Don't categorize Resource Groups based on resource type
@@ -58,4 +58,8 @@ There is no cost saving to group resources of the same type together. For exampl
 
 ::: bad
 ![Figure: Bad example - SSW.SQL has all the Databases for different apps in one place](arrange-azure-resources-bad.jpg)
-:::
+:::
+
+::: good
+![Figure: Good example (for all the above) - Resource Group contains all staging resources for this product](rg-good.png)
+:::
diff --git a/rules/choosing-authentication/rule.md b/rules/choosing-authentication/rule.md
@@ -53,7 +53,7 @@ Note that some of the options listed below support or include the features liste
 
 Each project is different, and you will need to consider your individual needs and circumstances when choosing how to implement identity and authentication in your solution. There are countless options available for authentication, but the chart below can provide a guide for some of the major decisions, and help you narrow down to some of the relevant options. Use this to get started and be sure to consider all the other information in this rule before making a decision.
 
-```mermaid
+```mermaid-svg
 flowchart
 
  Start(["Start"]) --> CustomLogic{"Need Custom/\nComplex Logic?"}

diff --git a/rules/do-you-use-co-creation-patterns/rule.md b/rules/do-you-use-co-creation-patterns/rule.md
@@ -5,19 +5,20 @@ uri: do-you-use-co-creation-patterns
 authors:
   - title: Daniel Mackay
     url: https://ssw.com.au/people/daniel-mackay
-related: []
+related: 
+  - over-the-shoulder
 created: 2022-11-21T00:28:43.256Z
 guid: 4ff555fd-3f4c-416b-9fc3-1bf9409cc0ab
 ---
-These days pull requests are the de facto standard for getting code reviewed.  Once a developer has finished their change, they will typically submit a pull request and move on to their next task.  This allows for an asynchronous process to take place which may seem like a good idea, but this can also lead to inefficiencies.
+These days Pull Requests are the de facto standard for getting code reviewed.  Once a developer has finished their change, they will typically submit a Pull Request and move on to their next task.  This allows for an asynchronous process to take place which may seem like a good idea, but often is not and can also lead to inefficiencies.
 
-## Problem - Inefficient Code Reviews
+## ❌ Problem - Inefficient Code Reviews
 
 Inefficient code reviews can be caused by:
 
-* Requesting feedback too Late
+* Requesting feedback too late
 * Receiving feedback too slow
-* Creating large pull requests
+* Creating large Pull Requests
 * Excessive context switching
 * Too much work in progress
 * Unclear feedback
@@ -30,37 +31,32 @@ Inefficient code reviews can be caused by:
 ![Figure: Inefficiencies caused by asynchronous code reviews (source: https://www.infoq.com/articles/co-creation-patterns-software-development)](co-creation-2.png)
 :::
 
-## How to Make Code Reviews More Efficient
+## ✅ How to Make Code Reviews More Efficient
 
-There are several improvements we can make to address some of the issues above.
-
-* Ask for feedback early
-
-  * Especially if you are uncertain
-* Provide clear feedback
-
-  * Be explicit and suggest the exact code changes where possible (GitHub has a feature for this)
-  * Contact the developer directly for more complicated changes
+* Author - [Do over the shoulder reviews](https://www.ssw.com.au/rules/over-the-shoulder/)
+* Author - Ask for feedback early before the PR, if you are uncertain that you're on the correct path
 * Limit work in progress
-
-  * Chasing up your outstanding pull requests before starting something new
-  * Reviewing other developer's pull requests before starting something new
-* Create small pull requests
-
+  * Author - Make sure your Pull Requests are merged, before starting a new task
+  * Reviewer - Prioritize Pull Requests before starting a new task
+* Author - Create small Pull Requests
   * This requires a smaller block of time to review which makes it easier for the reviewer to find the time
   * Less risk - reduces the chance of an incorrect approach being taken
   * Get quality feedback - small blocks of code are easier to digest
+* Reviewer - When reviewing asynchronously
+  * Be explicit and suggest the exact code changes where possible (GitHub has a feature for this, see https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request)
+  * Call the developer for more complicated changes
 
 ## The Ultimate Solution - Co-Creation Patterns
 
-Small pull requests have many benefits as outlined above.  However, each pull request comes with an overhead and making pull requests too small can introduce unnecessary waste and negatively affect the throughput of code.  In order to not lose throughput with small PRs, reviewers need to react faster
+Small Pull Requests have many benefits as outlined above.  However, each Pull Request comes with an overhead and making Pull Requests too small can introduce unnecessary waste and negatively affect the throughput of code.  In order to not lose throughput with small PRs, reviewers need to react faster
 That leads us to synchronous, continuous code reviews and co-creation patterns
 
  So, with the async way of working, we’re forced to make a trade-off between losing quality (big PRs) and losing throughput (small PRs).
 
 We can avoid this by using co-creation patterns.
 
-> As a general rule pull requests with less that 20 lines of code and larger changes with a degree of complexity or risk make good candidates for co-creation
+> As a general rule, Pull Requests with less than 20 lines of code, 
+> and larger changes with a degree of complexity/risk, make good candidates for co-creation
 
 ### Patterns
 
@@ -79,4 +75,10 @@ Co-creation allows us to have both quality and throughput by providing the follo
 4. Faster course correction
 5. Less delay - no waiting
 6. Eliminates context switching - working on a change together reduces WIP which further increases throughput
-7. Emotions are removed - instead of having an 'author' and 'critic', the code is created together.
+7. Emotions are removed - instead of having an 'author' and 'critic', the code is created together.
+
+<!-- 
+TODO: Add a PR screenshot of pair programming, show the PR Dan M with Jack R for the big PR for Rules GPT
+TODO: Add a PR screenshot of mob programming, we need to demonstrate what the PR would look like for this
+ -->
+
diff --git a/rules/follow-up-after-spec-review/rule.md b/rules/follow-up-after-spec-review/rule.md
@@ -17,11 +17,11 @@ At the end of the Spec Review presentation with the client, work out a good time
 
 <!--endintro-->
 
-## Objectives of the Follow-Up Meeting
+## Objectives of the follow-up meeting
 
 The follow-up meeting is a crucial step in ensuring a smooth transition from the Spec Review to the initiation of the project. Here's why and how we conduct this meeting:
 
-### 1. **Reaffirming Priorities**
+#### 1. Reaffirming priorities
 
 Revisit the MVP backlog to ensure there has been no shift in priorities. It's essential to keep the project aligned with the client's expectations and business objectives.
 
@@ -34,27 +34,27 @@ Account Manager: "No problem, we can re-evaluate the backlog and adjust the esti
 Good example - Adapting to client’s evolving priorities maintains alignment and trust
 :::
 
-### 2. **Encouraging New Insights**
+#### 2. Encouraging new insights
 
 The Spec Review often sparks new ideas or considerations. Encourage the client to share any fresh insights or concerns, which could be pivotal for the project.
 
-### 3. **Clarifying Estimates and Timelines**
+#### 3. Clarifying estimates and timelines
 
 Present an updated estimate reflecting any changes post Spec Review, ensuring clarity on the number of Sprints, developers needed, and the overall cost.
 
-### 4. **Outlining Next Steps**
+#### 4. Outlining next steps
 
 Clearly outline the subsequent steps, identifying any immediate actions required from either party to move forward.
 
-### 5. **Improving Through Feedback**
+#### 5. Improving through feedback
 
 Retro - Solicit feedback on the Spec Review process to continuously refine it, enhancing the experience for future projects.
 
-### 6. **Addressing Legal and Administrative Details**
+#### 6. Addressing legal and administrative details
 
 Delve into any T&Cs, NDAs, or other administrative details requiring attention before project commencement.
 
-## Appointment Template
+### Appointment template
 
 To facilitate the scheduling of the follow-up meeting, here's a template that the Account Manager can use:
 

diff --git a/rules/handle-noise-email/rule.md b/rules/handle-noise-email/rule.md
@@ -16,12 +16,12 @@ authors:
 
 Emails that are automatically generated can quickly overload your inbox with less important messages e.g. notifications from Microsoft Teams, GitHub, Azure Devops, etc.
 
-![Inbox with noise email](Inbox-with-noise-email.png)
-
-**❌ Figure: Inbox with noise from Azure Devops**
+::: bad  
+![Figure: Inbox with noise from Azure Devops](Inbox-with-noise-email.png)
+:::
 
 You can create a folder and rules in your Microsoft Outlook to move noisy emails out of the inbox based on the sender. [This article](https://support.microsoft.com/en-gb/office/always-move-messages-from-a-specific-sender-e28d03c0-077d-4366-a348-4536f0fc9008) shows how to move messages from specific senders.
 
-![Noise email in individual folder](Noise-email-in-individual-folder.png)
-
-**✅ Figure: Using a rule we can move noisy Azure DevOps emails to a newly created folder**
+::: good  
+![Figure: Using a rule we can move noisy Azure DevOps emails to a newly created folder](Noise-email-in-individual-folder.png)
+:::
diff --git a/rules/over-the-shoulder/rule.md b/rules/over-the-shoulder/rule.md
@@ -10,10 +10,11 @@ authors:
   - title: Adam Cogan
     url: https://www.ssw.com.au/people/adam-cogan
 related:
-  - over-the-shoulder-prs
   - do-you-know-the-3-steps-to-a-pbi
   - do-you-use-co-creation-patterns
   - merge-debt
+redirects:
+  - over-the-shoulder-prs
 created: 2023-05-15T21:36:54.519Z
 guid: f20af960-7a60-499c-980b-bd5bb6a0af91
 ---

diff --git a/rules/sprint-review-retro-email/rule.md b/rules/sprint-review-retro-email/rule.md
@@ -148,7 +148,7 @@ As part of our commitment to inspect and adapt as a team we conduct a Sprint Ret
 
 {{ INSERT DEFINITION OF DONE (Normally saying that it compiles, meets the acceptance criteria, and a test please has been sent if relevant) }} 
 
-&lt; This is as per the rule https://ssw.com.au/rules/do-you-create-a-sprint-review-retro-email /&gt;
+&lt; This is as per the rule [https://ssw.com.au/rules/sprint-review-retro-email](/sprint-review-retro-email) /&gt;
 
 :::
 :::