Review!

wouterj · wouterj · commit dbaaf7f17335 · 2016-07-14T20:57:13.000+02:00
diff --git a/service_container/alias_private.rst b/service_container/alias_private.rst
@@ -1,8 +1,8 @@
 .. index::
     single: DependencyInjection; Advanced configuration
 
-Service Aliases & Private Services
-==================================
+How to Create Service Aliases and Mark Services as Private
+==========================================================
 
 .. _container-private-services:
 
diff --git a/service_container/configurators.rst b/service_container/configurators.rst
@@ -1,8 +1,8 @@
 .. index::
    single: DependencyInjection; Service configurators
 
-Configuring Services with a Service Configurator
-================================================
+How to Configure a Service with a Configurator
+==============================================
 
 The *service configurator* is a feature of the service container that allows
 you to use a callable to configure a service after its instantiation.
diff --git a/service_container/definitions.rst b/service_container/definitions.rst
@@ -1,14 +1,21 @@
 .. index::
     single: DependencyInjection; Service definitions
 
-Working with Container Service Definitions
-==========================================
+How to work with Service Definition Objects
+===========================================
 
 Service definitions are the instructions describing how the container should
 build a service. They are not the actual services used by your applications.
 The container will create the actual class instances based on the configuration
 in the definition.
 
+Normally, you would use YAML, XML or PHP to describe the service definitions.
+But if you're doing advanced things with the service container, like working
+with a :doc:`Compiler Pass </service_container/compiler_passes>` or creating a
+:doc:`Dependency Injection Extension </bundles/extension>`, you may need to
+work directly with the ``Definition`` objects that define how a service will be
+instantiated.
+
 Getting and Setting Service Definitions
 ---------------------------------------
 
diff --git a/service_container/parent_services.rst b/service_container/parent_services.rst
@@ -1,8 +1,8 @@
 .. index::
     single: DependencyInjection; Parent services
 
-Managing Common Dependencies with Parent Services
-=================================================
+How to Manage Common Dependencies with Parent Services
+======================================================
 
 As you add more functionality to your application, you may well start to
 have related classes that share some of the same dependencies. For example,
diff --git a/service_container/service_decoration.rst b/service_container/service_decoration.rst
@@ -1,8 +1,8 @@
 .. index::
     single: Service Container; Decoration
 
-How to Decorating Services
-==========================
+How to Decorate Services
+========================
 
 When overriding an existing definition (e.g. when applying the `Decorator pattern`_),
 the original service is lost:
