diff --git a/docs/src/main/asciidoc/getting-started-testing.adoc b/docs/src/main/asciidoc/getting-started-testing.adoc
index ab8ff2b88e4dc..6a13199331b05 100644
--- a/docs/src/main/asciidoc/getting-started-testing.adoc
+++ b/docs/src/main/asciidoc/getting-started-testing.adoc
@@ -1236,7 +1236,30 @@ public @interface WithRepeatableTestResource {
 }
 ----
 
-
+=== Usage of `@WithTestResources`
+
+While test resources provided by `@QuarkusTestResource` are available either globally or restricted to the annotated test class (`restrictToAnnotatedClass`), the annotation `@WithTestResources` allows to additionally group tests by test resources for execution.
+`@WithTestResources` has a `scope` property that takes a `TestResourceScope` enum value:
+
+- `TestResourceScope.MATCHING_RESOURCES` (default) +
+Quarkus will group tests with the same test resources and run them together. After a group has been executed, all test resources will be stopped, and the next group will be executed.
+- `TestResourceScope.RESTRICTED_TO_CLASS` +
+The test resource is available only for the annotated test class and will be stopped after the test class has been executed. This is equivalent to using @QuarkusTestResource with restrictToAnnotatedClass = true.
+- `TestResourceScope.GLOBAL` +
+The test resource is available globally.
+This is equivalent  to using `@QuarkusTestResource` with `restrictToAnnotatedClass = false`.
+
+NOTE: `@QuarkusTestResource` is merely a convenient extension of `@WithTestResources` for the use of global test resources
+
+BELOW TO EDIT: +
+I don't know the behaviour when different scopes are mixed 🤷‍♂️Example:
+```java
+@WithTestResources(value = TestResourceA.class, scope = TestResourceScope.MATCHING_RESOURCES)
+@WithTestResources(value = TestResourceB.class, scope = TestResourceScope.RESTRICTED_TO_CLASS)
+@WithTestResources(value = TestResourceC.class, scope = TestResourceScope.GLOBAL)
+class TestClass(){}
+```
+Also maybe add a use case example for why this annotation got introduced and what for the different scopes are useful, as we currently only use GLOBAL because of time reason.
 
 == Hang Detection