Merge branch 'SSWConsulting:main' into cms/stephanfakossw/SSW.Rules.C…

…ontent/rule/maximize-superannuation-benefits/rule
SSWConsulting · Oct 30, 2024 · 7d13890 · 7d13890
1 parent c723ec1
commit 7d13890
Show file tree

Hide file tree

Showing 20 changed files with 654 additions and 61 deletions.
diff --git a/categories/design/rules-to-better-figma.md b/categories/design/rules-to-better-figma.md
@@ -7,7 +7,8 @@ index:
 - software-for-ux-design
 - figma-prototypes
 - figma-uses
-
+- figma-dev-mode
+
 ---
 
 Enhance your design process with these essential rules for using Figma, covering crucial software choices for UX design, effective prototyping techniques, and diverse applications of Figma in your workflow.
diff --git a/categories/software-engineering/rules-to-better-architecture-and-code-review.md b/categories/software-engineering/rules-to-better-architecture-and-code-review.md
@@ -59,6 +59,7 @@ index:
   - use-prefixes-to-improve-code-review-communication
   - use-mass-transit
   - software-architecture-decision-tree
+  - multi-tenancy-models
 ---
 
 For any project that is critical to the business, it’s important to do ‘Modern Architecture Reviews’. Being an architect is fun, you get to design the system, do ongoing code reviews, and play the bad ass. It is even more fun when using modern cool tools.

diff --git a/categories/software-engineering/rules-to-better-microservices.md b/categories/software-engineering/rules-to-better-microservices.md
@@ -8,6 +8,8 @@ index:
 - microservice-key-components
 - use-mass-transit
 - software-architecture-decision-tree
+- review-microservice-boundaries
+- prioritize-devex-in-microservices
 
 ---
 A microservice architecture is an application architecture where an application consists of many loosely-coupled services. The communications between services are kept lightweight, and the API interfaces between them need to be carefully managed. They are designed to allow different teams to work on different parts of the application completely independently.
diff --git a/categories/software-engineering/rules-to-better-net-projects.md b/categories/software-engineering/rules-to-better-net-projects.md
@@ -75,6 +75,7 @@ index:
 - dev-containers
 - containerize-sql-server
 - minimal-apis
+- directory-build-props
 
 ---
 

diff --git a/categories/software-engineering/rules-to-better-pull-requests.md b/categories/software-engineering/rules-to-better-pull-requests.md
@@ -24,6 +24,7 @@ index:
 - page-owner
 - clean-git-history
 - pr-suggest-changes
+- mandatory-vs-suggested-pr-changes
 ---
 
 Pull Requests are the backbone of an effective development team. That's why it's crucial to ensure that everyone on the team understands the expectations around Pull Requests.
diff --git a/categories/software-engineering/rules-to-better-web-api-rest.md b/categories/software-engineering/rules-to-better-web-api-rest.md
@@ -14,6 +14,7 @@ index:
 - do-you-return-detailed-error-messages
 - do-you-return-the-correct-response-code
 - use-fluent-validation
+- rest-api-design
 
 ---
 

diff --git a/rules/concise-writing/rule.md b/rules/concise-writing/rule.md
@@ -24,9 +24,25 @@ In today's fast-paced world, lengthy emails, web content, and instant messages c
 
 <!--endintro-->
 
-### Less is more
+## Embrace the principle of "less is more"
 
-To ensure effective written communication, it's crucial to embrace the principle of "less is more". By being concise and focusing on relevant information only, we can capture the reader's attention and prevent important messages from being overlooked or postponed due to time constraints. So, let's keep it **short**, **direct**, and **to the point**, ensuring our messages are accessible and impactful, even for busy individuals on the go.
+By being concise and focusing on relevant information only, we can capture the reader's attention and prevent important messages from being overlooked or postponed due to time constraints.
+
+::: greybox
+"The team conducted a comprehensive evaluation of the project’s scope and objectives to determine the best course of action moving forward."
+:::
+::: bad
+Bad example - Unnecessary filler words
+:::
+
+::: greybox
+"The team has evaluated the project."
+:::
+::: good
+Good example - Fewer words without losing meaning.
+:::
+
+Keep your writing **short**, **direct**, and **to the point**, ensuring our messages are accessible and impactful, even for busy individuals on the go.
 
 > "I didn't have time to write a short letter, so I wrote a long one instead."  
 > Mark Twain
diff --git a/rules/directory-build-props/rule.md b/rules/directory-build-props/rule.md
@@ -0,0 +1,122 @@
+---
+seoDescription: Simplify and streamline your .NET projects by using the Directory.Build.props file. Learn how this MSBuild feature centralizes configuration for multiple projects, reduces redundancy, and improves maintainability for enterprise-level .NET solutions. Discover how to manage common settings like .NET framework version, nullability, implicit references, and static code analysis efficiently across your solution.
+type: rule
+title: Do you use Directory.Build.Props to simplify multi-project build configurations?
+uri: directory-build-props
+authors:
+  - title: Daniel Mackay
+    url: https://www.ssw.com.au/people/daniel-mackay
+  - title: Luke Cook
+    url: https://www.ssw.com.au/people/luke-cook
+created: 2024-10-28T17:00:00.000Z
+guid: E3F562C1-30FF-4982-B96F-2AA0A716E842
+---
+
+When working on large enterprise scale projects .NET Solutions can often become unwieldy and difficult to maintain. This is particularly true of `.csproj` files which end up repeating configuration across all projects. How can one file save you hours of maintenance by keeping project configuration DRY?
+
+<!--endintro-->
+
+## What is a Directory.Build.props file?
+
+A [Directory.Build.props](https://learn.microsoft.com/en-us/visualstudio/msbuild/customize-by-directory?view=vs-2022) file is an MSBuild file used in .NET projects to define common properties and configurations that apply to multiple projects within a directory tree. This file helps centralize the configuration and reduce redundancy by allowing you to specify settings that will be inherited by all projects under the directory where the file is located.
+
+### Usages
+
+This can be used for:
+
+* .NET framework version
+* Nullability
+* Implicit references
+* Configuring warnings as errors
+* Static code analysis
+* Author / Company
+
+### Examples
+
+::: greybox
+
+**Project1.csproj:**
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+
+    <!-- Configure code analysis. -->
+    <AnalysisLevel>latest</AnalysisLevel>
+    <AnalysisMode>Recommended</AnalysisMode>
+    <TreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</TreatWarningsAsErrors>
+    <CodeAnalysisTreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</CodeAnalysisTreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+  </PropertyGroup>
+
+</Project>
+```
+
+**Project2.csproj:**
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+    <PropertyGroup>
+        <TargetFramework>net8.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+
+        <!-- Configure code analysis. -->
+        <AnalysisLevel>latest</AnalysisLevel>
+        <AnalysisMode>Recommended</AnalysisMode>
+        <TreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</TreatWarningsAsErrors>
+        <CodeAnalysisTreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</CodeAnalysisTreatWarningsAsErrors>
+        <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    </PropertyGroup>
+
+</Project>
+```
+
+:::
+::: bad
+Bad example - Redundant configuration
+:::
+
+::: good
+**Project1.csproj:**
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+</Project>
+```
+
+**Project2.csproj:**
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk.Web">
+</Project>
+```
+
+**Directory.Build.props:**
+
+```xml
+<Project>
+    <PropertyGroup>
+        <TargetFramework>net8.0</TargetFramework>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <Nullable>enable</Nullable>
+
+        <!-- Configure code analysis. -->
+        <AnalysisLevel>latest</AnalysisLevel>
+        <AnalysisMode>Recommended</AnalysisMode>
+        <TreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</TreatWarningsAsErrors>
+        <CodeAnalysisTreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</CodeAnalysisTreatWarningsAsErrors>
+        <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    </PropertyGroup>
+</Project>
+```
+
+:::
+::: good
+Good example - Centralized configuration
+:::
diff --git a/rules/do-you-know-the-how-to-be-a-good-product-owner/rule.md b/rules/do-you-know-the-how-to-be-a-good-product-owner/rule.md
@@ -33,16 +33,16 @@ The client is generally the Product Owner (PO). They should read the Scrum Guide
 2. **Decision-Making Authority - The PO has the authority to make key decisions**  
    The Product Owner must have the authority to make decisions regarding product features, priorities, and scope to keep the project moving forward.
 
-3. **Communication and Collaboration - The PO can communicate and collaborate effectively**  
+3. **Prioritization and Backlog Management - The PO is skilled at prioritizing and managing the backlog**  
+   A strong Product Owner excels at backlog management, making tough decisions on what features to prioritize to maximize ROI and deliver business value. They should ensure the backlog is always aligned with changing business needs and available resources.
+
+4. **Communication and Collaboration - The PO can communicate and collaborate effectively**  
    The Product Owner must be an effective communicator with both technical and non-technical stakeholders, translating business needs into technical requirements and explaining complexities back to the business. They should also collaborate closely with stakeholders, developers, and the Scrum Master to ensure everyone is aligned on goals and priorities. They should be adept at negotiating scope and timelines when necessary. They should also understand Product Backlog Items (PBIs) and be able to explain what they want using [Acceptance Criteria](/acceptance-criteria). This is the main way that developers and POs sync their understanding of what needs to be done.
 
     ::: greybox
     **Note:** It is helpful for developers to distinguish acceptance criteria between what is considered "essential" and what is merely "nice to have," as this can prevent them from investing excessive time in meeting non-essential criteria.
     :::
 
-4. **Prioritization and Backlog Management - The PO is skilled at prioritizing and managing the backlog**  
-   A strong Product Owner excels at backlog management, making tough decisions on what features to prioritize to maximize ROI and deliver business value. They should ensure the backlog is always aligned with changing business needs and available resources.
-
 5. **Availability and Commitment - The PO is available and committed to the team**  
    The Product Owner must be available to the team regularly to answer questions, provide feedback, and make decisions quickly. Their commitment to participating in [Sprint Reviews](/do-you-know-what-happens-at-a-sprint-review-meeting), [Retrospectives](/do-you-know-what-happens-at-a-sprint-retrospective-meeting) and [Sprint Planning](/what-happens-at-a-sprint-planning-meeting) meetings and staying connected to the team's progress (such as through [Daily Scrums](/methodology-daily-scrums)) is crucial to maintaining momentum. A good PO has a feeling of urgency!
 

diff --git a/rules/easy-recording-space/rule.md b/rules/easy-recording-space/rule.md
@@ -1,9 +1,7 @@
 ---
 type: rule
 title: Do you have a space to easily record awesome videos?
-seoDescription: Discover how to set up an effective video recording space that
-  ensures high-quality output, saves time, and avoids common pitfalls like
-  noise, poor lighting, and cluttered backgrounds.
+seoDescription: Discover how to set up an effective video recording space that ensures high-quality output, saves time, and avoids common pitfalls like noise, poor lighting, and cluttered backgrounds.
 uri: easy-recording-space
 authors:
   - title: Bahjat Alaadel
@@ -24,53 +22,47 @@ The popular open plan office will commonly result in poor vocal audio, bad light
 
 <!--endintro-->
 
-### Common Pitfalls to Avoid
+### Avoid common pitfalls
 
-When setting up your video recording space, be aware of these issues that can lead to a poor-quality video:
+When setting up the video recording space, be aware of these issues that can lead to a poor-quality video:
 
-::: greybox
-**Example 1:** Recording in a busy office with harsh fluorescent lights with background chatter and unpredictable changes to the ambient workspace volume and background elements.
-:::
+* **Busy environment** - Recording in a busy office with harsh fluorescent lights with background chatter and unpredictable changes to the ambient workspace volume and background elements
 
-::: bad
-![Figure: Bad Example - Shared noisy environment makes it hard to capture clear audio and branded visuals](https://github.com/user-attachments/assets/8da27a37-48e7-49d4-9779-755d11e42467)
-:::
+  ::: bad
+  ![Figure: Bad example - Shared noisy environment makes it hard to capture clear audio and branded visuals](https://github.com/user-attachments/assets/8da27a37-48e7-49d4-9779-755d11e42467)
+  :::
 
-::: greybox
-**Example 2:** Setting up and tearing down equipment each time you want to record.
-:::
+* **Non-permanent setup** - Setting up and tearing down equipment each time you want to record
 
-::: bad
-![Figure: Bad Example - Difficult setups leading to inconsistent quality and wasting time](https://github.com/user-attachments/assets/dfd4efca-8a93-4257-b09c-9689acc4ede7)
-:::
+  ::: bad
+  ![Figure: Bad example - Difficult setups leading to inconsistent quality and wasting time](https://github.com/user-attachments/assets/dfd4efca-8a93-4257-b09c-9689acc4ede7)
+  :::
 
-### How to Set Up an Effective Recording Space
+### How to set up an effective recording space
 
 A good recording space should be optimized for sound, lighting, background, and ease of use. Here are some tips:
 
-1. **Create a Soundproof Environment**
-   * Use a quiet room, preferably away from noisy areas.
-   * Consider soundproofing with foam panels, carpets, or curtains to minimize echoes and background noise.
+1. **Create a soundproof environment**
+   * Use a quiet room, preferably away from noisy areas
+   * Consider soundproofing with foam panels, carpets, or curtains to minimize echoes and background noise
 
-2. **Set Up Proper Lighting**
-   * Use soft, diffused lighting to avoid harsh shadows. Ring lights, softboxes, or LED panels can help.
-   * Ensure the lighting setup is consistent and avoids flickering or changes during recording.
+2. **Set up proper lighting**
+   * Use soft, diffused lighting to avoid harsh shadows. Ring lights, softboxes, or LED panels can help
+   * Ensure the lighting setup is consistent and avoids flickering or changes during recording
 
-3. **Choose a Clean, Professional Background**
-   * Opt for a neutral or branded background that is visually appealing and not overly busy.
-   * Consider a dedicated backdrop or a wall with minimal design to keep the focus on the speaker.
+3. **Choose a [clean, professional background](/unique-office-backgrounds)**
+   * Opt for a neutral or branded background that is visually appealing and not overly busy
+   * Consider a dedicated backdrop or a wall with minimal design to keep the focus on the speaker
 
-4. **Plug and Play Equipment Setup**
-   * Keep your camera, microphone, and lighting equipment permanently set up and ready to go. A "plug and play" system minimizes setup time and ensures consistent quality.
-   * Use a tripod for your camera and adjustable stands for lighting, so they are always in the correct position.
-   * Consider an external microphone for better sound quality, and test audio levels regularly.
+4. **Plug and play equipment setup**
+   * Keep your camera, microphone, and lighting equipment permanently set up and ready to go. A "plug and play" system minimizes setup time and ensures consistent quality
+   * Use a tripod for your camera and adjustable stands for lighting, so they are always in the correct position
+   * Consider an external microphone for better sound quality, and test audio levels regularly
 
-::: greybox
-**Good Example:** An office pod or studio with soundproofing, diffused soft lighting, and a mounted camera. The microphone is attached to the desk, and the background is a clean, branded wall with subtle colors. Equipment remains in place, so the recording can begin within minutes.
-:::
+An office pod or studio with soundproofing, diffused soft lighting, and a mounted camera. The microphone is attached to the desk, and the background is a clean, branded wall with subtle colors. Equipment remains in place, so the recording can begin within minutes.
 
 ::: good
-![Figure: Good Example - Plug and play system that ensures consistent quality and saves time](https://github.com/user-attachments/assets/883aff45-3714-478d-9365-ba98aac57a06)
+![Figure: Good example - Plug and play system that ensures consistent quality and saves time](https://github.com/user-attachments/assets/883aff45-3714-478d-9365-ba98aac57a06)
 :::
 
 By setting up a dedicated recording space that addresses these factors, you can streamline your workflow, reduce stress, and consistently produce high-quality videos that engage your audience. Spend time to get your space right once, and you’ll save hours on every future recording session.