diff --git a/approvaltests/docs/explanations/RemovingEnvironmentAwareReporter.md b/approvaltests/docs/explanations/RemovingEnvironmentAwareReporter.md
index b53b0bdf..31da069c 100644
--- a/approvaltests/docs/explanations/RemovingEnvironmentAwareReporter.md
+++ b/approvaltests/docs/explanations/RemovingEnvironmentAwareReporter.md
@@ -7,13 +7,55 @@ Before October 2023 "ApprovalTests 19.0.0" and before,
 
 ```mermaid
 classDiagram
-    interface EnvironmentAwareReporter{
+    class ApprovalFailureReporter{
+<<interface>>
+        +report(String received, String approved): void
+    }
+    class EnvironmentAwareReporter{
+<<interface>>
         +isWorkingInThisEnvironment(String forFile): boolean
     }
-    interface ApprovalFailureReporter{
-        +report(String received, String approved): void
+    ApprovalFailureReporter <|-- EnvironmentAwareReporter
+```
+
+This allowed us to use chain of responsibility to determine which Reporter to use.
+The problem with `isWorkingInThisEnvironment` is that it is **predictive** but not **complete**.
+It is saying that it should work in this environment but maybe something goes wrong when you actually do it.
+Instead, we've combined this into
+
+```mermaid
+classDiagram
+    class ApprovalFailureReporter{
+<<interface>>
+        +report(String received, String approved): boolean
     }
-    EnvironmentAwareReporter <|-- ApprovalFailureReporter
 ```
 
+When you call report, the reporter now tells you if it worked.
+
+## How to upgrade
+
+### Upgrading an EnvironmentAwareReporter
+
+For an EnvironmentAwareReporter there are two things you have to do.
+1. Change EnvironmentAwareReporter to ApprovalFailureReporter
+2. Change the reporter:
+
+```java
+
+public boolean report(String received, String approved)
+{
+    if (!isWorkingInThisEnvironment(received))
+    {
+      return false;
+    }
+    // old reporter code here
+    return true;
+}
+```
+
+`isWorkingInThisEnvironment()` can be made private now usually or inlined.
+
+### Upgrading an ApprovalFailureReporter 
 
+* Add `return true;` to the end of your `report(String received, String approved)` method to satisfy the compiler.