Merge branch 'SSWConsulting:main' into main

categories/marketing-and-video/rules-to-better-video-recording.md

@@ -10,6 +10,7 @@ index:
 - pre-production-do-you-test-technical-scripts-properly
 - define-the-level-of-quality-up-front
 - developer-console-screenshots
+- focus-peaking
 - production-do-you-add-a-call-to-action
 - production-do-you-know-how-to-conduct-an-interview
 - production-do-you-know-how-to-record-live-video-interviews-on-location

categories/software-development/rules-to-better-github.md

@@ -44,7 +44,8 @@ index:
   - avoid-auto-closing-issues
   - enterprise-secrets-in-pipelines
   - use-pull-request-templates-to-communicate-expectations
-  - use-squash-and-merge-for-open-source-projects 
+  - use-squash-and-merge-for-open-source-projects
+  - keeping-pbis-status-visible
 ---
 
 [GitHub](https://github.com) is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere.

rules/do-you-know-what-happens-at-a-sprint-review-meeting/rule.md

@@ -46,6 +46,9 @@ In Scrum, there are 4 meetings in total that you need to know about:
 
 
 #### What if you can't attend the Sprint Review
+
+![Figure: Playing golf](Golf-holiday.png)  
+
 If you can't attend your team's Sprint Review (e.g. you're on leave, working part-time, or in a different timezone), you should give the team a summary of where you're at, so they can inform the stakeholders on your behalf.
 
 - Send a brief "Sprint Review" email to the team to provide them with an update on the status of your tasks. This will enable the team to pass on the information to the client.

rules/do-you-know-what-sort-of-insurance-to-buy-when-travelling/rule.md

@@ -28,10 +28,11 @@ For example, if you're travelling  **within your home country** you might decide
 :::
 
 
-::: good  
+
 ![](575bdf\_private-travel-insurance.jpg)  
+::: good  
+ **Figure: Good example - Allianz travel insurance for within Australia covers up to AUD$6,000 excess on a rental vehicle – this works out to be about $5.15 a day for a 9-day trip**
 :::
- Figure: Good example: Allianz travel insurance for within Australia covers up to AUD$6,000 excess on a rental vehicle – this works out to be about $5.15 a day for a 9-day trip
 ### International travel:
 
 If you're  **travelling outside of the country** , you should definitely take out travel insurance. If you book and pay using a credit card, you might be eligible for free travel insurance through your credit card institution, but don't assume this cover will be right for your needs, or will necessarily cover the whole travel party.

rules/do-you-return-detailed-error-messages/rule.md

@@ -8,34 +8,118 @@ created: 2015-08-27T01:00:17.0000000Z
 authors:
 - title: Jeremy Cade
   url: https://ssw.com.au/people/jeremy-cade
+- title: Chris Clement
+  url: https://www.ssw.com.au/people/chris-clement
 related: []
 redirects: []
 
 ---
 
-Good error design is as important to the sucess of an API as the API design itself. A good error message provides context and visibility on how to troubleshoot and resolve issues at critical times.
+Good error design is as important to the success of an API as the API design itself. A good error message provides context and visibility on how to troubleshoot and resolve issues at critical times.
 
 <!--endintro-->
 
-### For REST, start by using the correct HTTP Status Codes...
+## REST API
+### Use the correct HTTP Status Codes
 
+The HTTP/1.1 RFC lists over 70 different HTTP Status Codes. Only some developers will be able to remember all of them, so it pays to keep it simple and use the most common Status Codes. Below are the most common HTTP status codes:
 
-The HTTP/1.1 RFC lists over 70 different HTTP Status Codes. Very few developers will be able to remember all of them, so it pays to keep it simple and use the most common Status Codes. The basic rule is to use the following three:
+* **2XX** - Success. Examples:
+  * 200 OK - Generic success response.
+* **4XX** - Client errors. Examples:
+  * 400 Bad Request - The server cannot understand the request.
+  * 401 Unauthorised - Invalid/non-existent credential for this request.
+* **5XX** - Server errors. Examples:
+  * 500 Internal Server Error - The server encountered errors preventing the request from being fulfilled.
 
-* **200 OK** - Everything worked. Success
-* **400 Bad Request** - The consuming application did something wrong.
-* **500 Internal Server Error** - The API Application did something wrong.
 
-### ...And then include the problem details
-RFC 7807 - Problem Details for HTTP APIs (ietf.org) details the specification for returning errors from your API. The HTTP Status Codes are an excellent start - they immediately tell you *where*the problem is, but they don't tell you *what*the problem is.
+### Use ProblemDetails Format
+[RFC 7807 - Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807.html) details the specification for returning errors from your API. 
 
-ASP.Net Core has built in support for the problem details specification. You can see more at the official documentation. Handle errors in ASP.NET Core web APIs | Microsoft Docs
+Problem Details defines a standardised way for HTTP APIs to communicate errors to clients. It introduces a simple and consistent format for describing errors, providing developers with a clear and uniform way to understand and handle errors in HTTP APIs.
 
-### And for any API (REST, gRPC and GraphQL):
+Below is an example of an error message in Problem Details format:
+```json
+{
+  "type": "https://example.com/probs/invalid-id",
+  "title": "Invalid ID",
+  "status": 400,
+  "detail": "The provided ID has invalid characters.",
+  "instance": "/account/12%203",
+  "allowedCharacters": "^[a-zA-Z0-9]+$"
+}
+```
+
+In the above example:
+- `type` specifies a URI that uniquely identifies the type of the problem.
+- `title` provides a short, human-readable summary of the problem.
+- `status` indicates the HTTP status code for the response.
+- `detail` gives a human-readable explanation specific to the occurrence of the problem.
+- `instance` provides a URI reference that identifies the specific occurrence of the problem.
+- `allowedCharacters` is an example property specificly added to the problem.
+
+Using the above structured message format, APIs can now reliably communicate problems to clients to enable better error handling.
+
+
+### Use .NET Exception Handler
+
+ASP.NET Core has built-in support for the problem details specification since .NET 7.
+
+### Option 1 - Use built-in ProblemDetails service
+
+```csharp
+// Program.cs
+// This adds ProblemDetails service
+// Read more on https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-8.0#problem-details
+builder.Services.AddProblemDetails();
+
+...
+
+// This instructs the API to use the built-in exception handler
+app.UseExceptionHandler();
+```
+
+Using this option, the API will generate a problem details response for all HTTP client and server error responses that *don't have body content yet*.
+
+You can also customise the `ProblemDetailsService` behaviour - read more about it in the following link [Handle errors in ASP.NET Core | Customise Problem Details](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-8.0#customize-problem-details).
+
+
+⚠️ **Important**
+The default .NET Exception Handler middleware will **only** produce ProblemDetails responses for exceptions when running in a non-Development [environment](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-7.0#environments). See Option 2 below on how to make this consistent across environments.
+
+
+### Option 2 - Customise Exception Handler Middleware (Recommended)
+
+This option provides more flexibility in controlling the API's behaviour when it encounters thrown exceptions. Read more about it [here](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-8.0&preserve-view=true#exception-handler-lambda).
+By Customising the `ExceptionHandler` middleware, developers have complete control over what format endpoints should return under a particular scenario.
+
+Below is an example of customising the `ExceptionHandler` middleware to produce a `ProblemDetails` response for any exception.
+
+```csharp
+app.UseExceptionHandler(exceptionHandlerApp =>
+  exceptionHandlerApp.Run(async context =>
+  {
+    // Obtain the exception
+    Exception? exception = context.Features.Get<IExceptionHandlerFeature>()?.Error;
+
+    // Produce a ProblemDetails response
+    await Results.Problem(
+      statusCode: StatusCodes.Status500InternalServerError,
+      type: "https://tools.ietf.org/html/rfc7231#section-6.6.1",
+      title: exception?.Message
+    ).ExecuteAsync(context);
+  }));
+```
+
+API will produce consistent response formats in any environment using the above approach.
+This approach is the recommended approach for frontend and backend development.
+
+
+## Any API (REST, gRPC and GraphQL):
 
-### Make your error messages as verbose as necessary...
+### Add Sufficient Details in Error Message
 
-Error messages should contain a sufficient level of information that a developer or consuming client can act upon.
+Error messages should contain sufficient information that a developer or consuming client can act upon.
 
 ```json
 {
@@ -57,7 +141,7 @@ Figure: Bad Example - The error message does not contain information that can be
 Figure: Good Example - The error message provides explicit detail and a short description on how to fix the issue.  
 :::
 
-### ...But no more verbose than that
+### Sanitize Response
 
 ```none
 HTTP/1.1 500 Internal Server Error

rules/duplicate-email-draft/rule.md

@@ -12,7 +12,11 @@ guid: 3726e23d-32f1-4810-b07a-97ca78d05971
 ---
 Sometimes it can be useful to have multiple copies of the same email.
 
-If you want to duplicate a particular message in Outlook, place the cursor in any of these fields: **To**, **Cc**, **Bc**, or **Subject**, and press **CTRL+F**. 
+If you want to duplicate a particular message in Outlook, place the cursor in any of these fields: **To**, **Cc**, **Bc**, or **Subject**, and press **CTRL+F**.
+
+`youtube: https://youtu.be/20qslwUxFEg`
+
+  **Video: Duplicate an entire email in one keystroke in Microsoft Outlook (3 min)**
 
 ::: info
 **Note:** This works on **Outlook for Windows** only. Unfortunately, it doesn't work on **Outlook for Mac** nor **Outlook on the web**.

rules/email-send-a-v2/rule.md

@@ -23,7 +23,7 @@ guid: 11cb9562-d259-489f-a8e7-9dac55d2b7ac
 ---
 
 Sometimes you will need to send a new version for an email. This often is due to 2 main reasons:
-  - You **received a substantial feedback** about the email you've sent that requires a new version
+  - You **received substantial feedback** about the email you've sent that requires a new version
   - You realized you've **made a mistake** and want to send an updated version of an email
 
 <!--endintro-->