XS✔ ◾ Improved capitalization and readability

rules/avoid-auto-closing-issues/rule.md

@@ -12,17 +12,17 @@ guid: 97504e80-fe64-427b-9a66-2b6508689411
 
 GitHub provides a way to link issues to PRs. This is useful to see what PRs are associated with what issues. However, when you make this link, the issue will close when the PR is merged.
 
-This is not a good idea because it can cause issues to be closed prematurely. This can lead to confusion and lost work.
+This is not a good idea because it can cause Issues to be closed prematurely. This can lead to confusion and lost work.
 
 <!--endintro-->
 
-Issues should not be closed until all the tasks are complete and have a done comment as per [Do you close PBIs with context?](/close-pbis-with-context/)
+Issues should not be closed until all the tasks are complete and have a done comment as per [closing PBIs with context](/close-pbis-with-context/).
 
 ::: bad
-![Figure: Bad Example - ](bad-link-issues-prs.png)
+![Figure: Bad example - Linking Issues to PRs might cause premature closing](bad-link-issues-prs.png)
 :::
 
 **Tip:** Avoid using closing keywords e.g. _"closes #123"_ or _"fixes #123"_ in PR descriptions. This will automatically link the issue to the PR and close it on PR merge.
 Instead, use terms like _"relates to #123"_ or _"addresses #123"_ to link the issue to the PR without closing it.
 
-This was a feature GitHub added but it is not a good idea to use it, if you agree the behaviour should be changed, go upvote this discussion <https://github.com/orgs/community/discussions/17308>
+This was a feature GitHub added but it is not a good idea to use it, if you agree the behaviour should be changed, [upvote this discussion](https://github.com/orgs/community/discussions/17308).

rules/do-you-save-failed-experiments-in-abandoned-pull-requests/rule.md

@@ -27,16 +27,10 @@ This makes sure that we have a historical log of work completed, and still keeps
 
 <!--endintro-->
 
-![](create-pr-for-failed-branch.png)
-
 ::: good
-Good Example: Setup pull request for feature branch so that we have a history of the commits
-
+![Figure: Good example - Setup pull request for feature branch so that we have a history of the commits](create-pr-for-failed-branch.png)
 :::
 
-![](abandoned-pr-for-branch.png)
-
 ::: good
-Good Example: PR is abandoned with a deleted branch
-
+![Figure: Good example - PR is abandoned with a deleted branch](abandoned-pr-for-branch.png)
 :::

rules/dont-push-your-pull-requests/rule.md

@@ -2,7 +2,7 @@
 seoDescription: Don't push your pull requests! Discuss then build to ensure seamless collaboration and better outcomes for open source projects.
 type: rule
 archivedreason:
-title: Do You Know to not 'Push' your Pull Requests? (aka discuss then build)
+title: Do you know to not 'Push' your Pull Requests? (aka discuss then build)
 guid: 4a8b579b-c602-429c-84f2-0f306d7ab9c3
 uri: dont-push-your-pull-requests
 created: 2016-03-29T18:35:55.0000000Z
@@ -15,18 +15,18 @@ redirects:
   - do-you-know-to-not-push-your-pull-requests-(a-k-a-discuss-then-build)
 ---
 
-For the original article check out [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/)by Ilya Grigorik.
+For the original article check out [Don't "Push" Your Pull Requests](https://www.igvita.com/2011/12/19/dont-push-your-pull-requests/) by Ilya Grigorik.
 
 Open source software projects love it when the community get involved and pitch in.
 
 It's great when someone fixes a bug.
 
-A short pull request to fix a small problem is easy to review and accept.
+A short PR to fix a small problem is easy to review and accept.
 
 <!--endintro-->
 
-It's great when someone adds a much-needed feature
-...as long as the feature fits in with the project the core contributors have for the project
+It's great when someone adds a much-needed feature...
+...as long as the feature fits in with the project the core contributors have for the project...
 ...and it meets the existing coding patterns and engineering standards.
 
 This is where frustration often starts to set in on open source projects.
@@ -35,45 +35,29 @@ A contributor has a great idea for a feature, or identifies an area where they c
 
 Their contribution might solve their problem, but after it has been accepted it will most likely be left for the core contributors to maintain.
 
-::: greybox
+## ❌ Poor communication contribution
 
-**# Poor Communication Contribution**
+Poor early communication can lead to mis-directed work and pull requests not being accepted.
 
-- developer has good idea for project
-- bashes away and writes 600 lines of code
-- submits pull request
-- core contributor looks at large pull request
-  she doesn't fully understand purpose of request / the problem it solves
-  she doesn't like that the PR author hasn't followed the existing coding standards
-  she makes a push back comment
+* Developer has good idea for project
+* Bashes away and writes 600 lines of code
+* Submits pull request
+* Core contributor looks at large pull request
+  They don't fully understand purpose of request / the problem it solves
+  They don't like that the PR author hasn't followed the existing coding standards
+  They make a push back comment
 
-:::
+## ✅ Good communication contribution
 
-::: bad
-Figure: Bad Example - Poor early communication can lead to mis-directed work and pull requests not being accepted  
-:::
+Good communication leads to collaboration and better outcomes for the author and the project.
 
-::: greybox
+* Developer (PR Author) has good idea for project
+* Reviews the list of outstanding issues for the project and confirms that someone hasn't already had the same idea and started a discussion on it
+* Author creates an issue on GitHub and outlines the problem they are trying to solve, and outlines their suggested solution
+* The core contributors and other interested parties can help refine both the idea for the feature and the suggested implementation
+* The author can then start working on the feature knowing that their idea for the project complies with the maintainers vision for the project and know it is likely to be merged into the core codebase
 
-**# Good Communication Contribution**
+## Projects with internal teams
 
-- developer (PR Author) has good idea for project
-- reviews the list of outstanding issues for the project and confirms that someone hasn't already had the same idea and started a discussion on it
-- author creates an issue on GitHub and outlines the problem they are trying to solve, and outlines their suggested solution
-- the core contributors and other interested parties can help refine both the idea for the feature and the suggested implementation
-- the author can then start working on the feature knowing that their idea for the project complies with the maintainers vision for the project and know it is likely to be merged into the core codebase
-
-:::
-
-::: good
-Figure: Good  Example - Good communication leads to collaboration and better outcomes for the author and the project  
-:::
-
-::: greybox
-
-**# Projects with Internal Teams**
-
-- Internal SSW team members should only work on features during work hours that have been assigned to a release by the core contributors for a project
-- Features will be assigned to a release during the Community Standup
-
-:::
+* Internal team members should only work on features during work hours that have been assigned to a release by the core contributors for a project
+* Features will be assigned to a release during the Community Standup