Add documentation

docs/_pages/introduction.md

@@ -170,3 +170,51 @@ Expected string to be "Expected" with a length of 8, but "Actual" has a length o
 
 For more information take a look at the [AssertionScopeSpecs.cs](https://github.com/fluentassertions/fluentassertions/blob/master/Tests/FluentAssertions.Specs/Execution/AssertionScopeSpecs.cs) in Unit Tests.
 
+### Scoped `IValueFormatter`s
+
+You can add a custom value formatter inside a scope to selectively customize formatting of an object based on the test's context.
+To achieve that, you can do following:
+
+```csharp
+using var outerScope = new AssertionScope();
+
+var outerFormatter = new OuterFormatter();
+outerScope.FormattingOptions.AddFormatter(outerFormatter);
+```
+
+You can even add formatters to nested assertion scopes and the nested scope will pick up all previous defined scopes:
+
+```csharp
+using var outerScope = new AssertionScope();
+
+var outerFormatter = new OuterFormatter();
+var innerFormatter = new InnerFormatter();
+outerScope.FormattingOptions.AddFormatter(outerFormatter);
+
+using var innerScope = new AssertionScope();
+innerScope.FormattingOptions.AddFormatter(innerFormatter);
+
+// At this point outerFormatter and inneroormatter will be available
+```
+
+**Note:** If you modify the scoped formatters inside the nested scope, it will leave the scoped formatters as is from the outer scope:
+
+```csharp
+using var outerScope = new AssertionScope();
+
+var outerFormatter = new OuterFormatter();
+var innerFormatter = new InnerFormatter();
+outerScope.FormattingOptions.AddFormatter(outerFormatter);
+
+using (var innerScope = new AssertionScope())
+{
+  innerScope.FormattingOptions.AddFormatter(innerFormatter);
+  innerScope.FormattingOptions.RemoveFormatter(outerFormatter);
+
+  // innerScope contains only innerFormatter
+}
+
+// outerScope contains only outerFormatter
+
+// At this point outerFormatter and inneroormatter will be available
+```