diff --git a/service_container.rst b/service_container.rst
index 006c59d7645..7c39997464c 100644
--- a/service_container.rst
+++ b/service_container.rst
@@ -923,6 +923,41 @@ them will not cause the container to be rebuilt.
     means that all classes are "available to be *used* as services" without needing
     to be manually configured.
 
+Multiple Service Definitions Using the Same Namespace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+    The ``namespace`` option in the YAML configuration was introduced in Symfony 3.4.
+
+If you define services using the YAML config format, the PHP namespace is used
+as the key of each configuration, so you can't define different service configs
+for classes under the same namespace:
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    services:
+        App\Domain\:
+            resource: '../../src/Domain/*'
+            # ...
+
+In order to have multiple definitions, add the ``namespace`` option and use any
+unique string as the key of each service config:
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            command_handlers:
+                namespace: App\Domain\
+                resource: '../../src/Domain/*/CommandHandler'
+                tags: [command_handler]
+
+            event_subscribers:
+                namespace: App\Domain\
+                resource: '../../src/Domain/*/EventSubscriber'
+                tags: [event_subscriber]
+
 .. _services-explicitly-configure-wire-services:
 
 Explicitly Configuring Services and Arguments