2.x Fix information about updated Twig filters (#2855)

* fix(docs): Fix information about updated Twig filters
* fix(docs): Fix contradictory instructions for timber/twig filter usage

docs/v2/guides/extending-twig.md

@@ -5,7 +5,11 @@ order: "1650"
 
 ## Twig Environment
 
-Timber abstracts some of that functionality for you, so you can add functions or filters more easily.
+Twig has a `\Twig\Environment` class that you can [use to extend Twig](https://twig.symfony.com/doc/3.x/advanced.html). One of the most common ways this is used is to add [functions](https://twig.symfony.com/doc/3.x/advanced.html#functions) and [filters](https://twig.symfony.com/doc/3.x/advanced.html#filters) to Twig. But it could also be used to add globals, extensions, and more.
+
+Timber creates a `\Twig\Environment` object for you. You can use the `timber/twig` filter to access that object and extend Twig through it.
+
+Timber further abstracts some of that functionality for you, so you can add functions or filters more easily.
 
 ## Functions
 

docs/v2/upgrade-guides/2.0.md

@@ -677,18 +677,26 @@ The following functions are now deprecated:
 
 ### Updated timber/twig filters
 
-In Timber 1.x, apart from `timber/twig`, we had other internal filters to filter the Twig Environment.
+In Timber 1.x, apart from `timber/twig`, we had various (non-official) filters to [filter the Twig Environment](https://timber.github.io/docs/v2/guides/extending-twig/#twig-environment).
 
 - `timber/twig/functions`
 - `timber/twig/filters`
 - `timber/twig/escapers`
 
-You shouldn’t use any of those anymore. In Timber 2.x, you should only use `timber/twig` to add your own functionality to the Twig Environment. If you use any of the following filters to filter the Twig Environment, you’ll get a `Call to a member function addFunction() on array` or a `Call to a member function addFilter() on array` error:
+You shouldn’t use any of those to add functionality to the Twig Environment (`\Twig\Environment`) anymore. In Timber 2.x, you should only use `timber/twig` to extend `\Twig\Environment`.
 
-- `timber/twig/functions`
-- `timber/twig/filters`
+If you use any of the above filters to extend the Twig Environment, you’ll get a `Call to a member function addFunction() on array` or a `Call to a member function addFilter() on array` error.
+
+Here’s how the filters are used in Timber 2.0:
+
+| Filter                  | Usage before                  | Usage now                   |
+|-------------------------|-------------------------------|-----------------------------|
+| `timber/twig`           | Extend `\Twig\Environment`    | Extend `\Twig\Environment`  |
+| `timber/twig/functions` | 🚫 Extend `\Twig\Environment` | ✅ Add/remove Twig functions |
+| `timber/twig/filters`   | 🚫 Extend `\Twig\Environment` | ✅ Add/remove Twig filters   |
+| `timber/twig/escapers`  | 🚫 Extend `\Twig\Environment` | ✅ Add/remove Twig escapers  |
 
-The other filters will be used to filter the functions, filters and escapers that are actually added to Twig by Timber. Check out the new [Extending Twig Guide](https://timber.github.io/docs/v2/guides/extending-timber/) to learn more.
+Check out the new [Extending Twig Guide](https://timber.github.io/docs/v2/guides/extending-twig/) to learn more and see some examples.
 
 ### Namespaced Twig locations