Refresh Change Wave Docs (dotnet#5770)

* Refresh docs for an easier read

* fix sentence

* PR Feedback

* PR Feedback

documentation/wiki/ChangeWaves-Dev.md

@@ -1,12 +1,10 @@
 ⚠ This doc is intended for internal teams.
 
 # What are Change Waves?
-A Change Wave is a set of risky features developed under the same opt-out flag. This flag happens to be the version of MSBuild that the features were developed for. The purpose of this is to warn developers of risky changes that will become standard functionality down the line. 
+A Change Wave is a set of risky features developed under the same opt-out flag. This flag happens to be the version of MSBuild that the features were developed for. The purpose of this is to warn developers of risky changes that will become standard functionality down the line.
 
 ## How do they work?
-The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the wave (or version) that contains the feature you want **disabled**. 
-
-**Note:** If  `MSBuildDisableFeaturesFromVersion` is set to `16.8`, this will **disable** all features under that `16.8` and **any further versions**.
+The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the Change Wave (or version) that contains the feature you want **disabled**. All later change waves are similarly disabled.
 
 ## What Are the Current Change Waves & Associated Features?
 See the mapping of change waves to features [here](ChangeWaves.md#change-waves-&-associated-features).
@@ -26,10 +24,10 @@ The Process:
 1. In the `Microsoft.Build` project, open `SharedUtilities\ChangeWaves.cs`.
 2. Add a const string to identify the new wave, following the format:
 ```c#
-public const string Wave17_4 = "17.4"
+public const string Wave17_4 = "17.4";
 ```
 3. You may need to delete the lowest wave as new waves get added.
-4. As you rotate in/out change waves, be sure to update the AllWaves array appropriately.
+4. Update the AllWaves array appropriately.
 ```c#
 public static readonly string[] AllWaves = { Wave16_10, Wave17_0, Wave17_4 };
 ```
@@ -81,9 +79,9 @@ using (TestEnvironment env = TestEnvironment.Create())
 }
 ```
 
-## Change Wave 'End of Lifespan' Procedure
+## Change Wave 'End-of-Lifespan' Procedure
 These features will eventually become standard functionality. When a change wave rotates out, do the following:
-1. Start by deleting the constant `Wave17_4` that was created in step one.
-2. Remove `ChangeWave.AreFeaturesEnabled` or `$([MSBuild]::AreFeaturesEnabled('17.4'))` conditions surrounding features that were assigned that change wave.
+1. Start by deleting the constant `Wave17_4` that was created in [Creating a Change Wave](#creating-a-change-wave).
+2. Remove `ChangeWave.AreFeaturesEnabled` or `[MSBuild]::AreFeaturesEnabled` conditions surrounding features that were assigned that change wave.
 3. Remove tests associated with ensuring features would not run if this wave were set.
 4. Clear all other issues that arose from deleting the constant.

documentation/wiki/ChangeWaves.md

@@ -1,15 +1,17 @@
 # What are Change Waves?
-A Change Wave is a set of risky features developed under the same opt-out flag. This flag happens to be the version of MSBuild that the features were developed for. The purpose of this is to warn developers of risky changes that will become standard functionality down the line. 
+A Change Wave is a set of risky features developed under the same opt-out flag. This flag happens to be the version of MSBuild that the features were developed for. The purpose of this is to warn developers of risky changes that will become standard functionality down the line.
 
 ## How do they work?
-The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the wave (or version) that contains the feature you want **disabled**. See the mapping of change waves to features below.
+The opt out comes in the form of setting the environment variable `MSBuildDisableFeaturesFromVersion` to the Change Wave (or version) that contains the feature you want **disabled**. See the mapping of change waves to features below.
 
-**Note:** If  `MSBuildDisableFeaturesFromVersion` is set to `16.8`, this will **disable** all features under that `16.8` and **any further versions**.
-
-## MSBuildDisableFeaturesFromVersion Values
-- If `MSBuildDisableFeaturesFromVersion` is not set, all change waves will **be enabled**
-- If `MSBuildDisableFeaturesFromVersion` is set to some out of bounds version (see current rotation of waves below), you will be defaulted to the lowest wave. This will **disable all waves**.
-- If `MSBuildDisableFeaturesFromVersion` is set to some invalid format (ex: 16x8, 17_0), all change waves will **be enabled**.
+## MSBuildDisableFeaturesFromVersion Values & Outcomes
+| `MSBuildDisableFeaturesFromVersion` Value                         | Result        | Receive Warning? |
+| :-------------                                                    | :----------   | :----------: |
+| Unset                                                             | All Change Waves will be enabled, meaning all features behind each Change Wave will be enabled.               | No   |
+| Any valid & current Change Wave (Ex: `16.8`)                      | All features behind Change Wave `16.8` and higher will be disabled.                                           | No   |
+| Invalid Value (Ex: `16.9` when valid waves are `16.8` and `16.10`)| Default to the closest valid value (ascending). Ex: Setting `16.9` will default you to `16.10`.               | No   |
+| Out of Rotation (Ex: `17.1` when the highest wave is `17.0`)      | Clamp to the closest valid value. Ex: `17.1` clamps to `17.0`, and `16.5` clamps to `16.8`                    | Yes  |
+| Invalid Format (Ex: `16x8`, `17_0`, `garbage`)                    | All Change Waves will be enabled, meaning all features behind each Change Wave will be enabled.               | Yes  |
 
 # Change Waves & Associated Features