[WIP] Revise the documentation

docs/intro/getting-started.md

@@ -2,35 +2,27 @@
 
 ## Prerequisites
 
-Disco needs at least [PHP](http://php.net) 7.0 since Disco relies on the
-[return type declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration)
-feature introduced with PHP 7.0.
+Disco needs at least [PHP](http://php.net) 7.0, as Disco relies on the [return type declarations](http://php.net/manual/en/functions.returning-values.php#functions.returning-values.type-declaration) feature introduced with PHP 7.0.
 
 ## Installation
 
-The preferred way of installing `bitexpert/disco` is through Composer. Simply require the `bitexpert/disco` package:
+The preferred way of installing `bitexpert/disco` is through Composer, by calling the following command:
 
-```
+```php
 composer.phar require bitexpert/disco
 ```
 
 ## Using Disco
 
-To instanciate Disco use the following code in your bootstrapping logic. Create
-an instance of the ```\bitExpert\Disco\AnnotationBeanFactory``` and register the
-instance with the ```\bitExpert\Disco\BeanFactoryRegistry```. The second step is
-important as Disco needs to grab the active container instance in a few locations
-where it does not have access to the container instance itself.
+To instantiate Disco you need to do two things:
 
-```php
-<?php
+1. Create a configuration class
+2. Bootstrap Disco
 
-$beanFactory = new \bitExpert\Disco\AnnotationBeanFactory(MyConfiguration::class);
-\bitExpert\Disco\BeanFactoryRegistry::register($beanFactory);
-```
+### Create a configuration class
 
-Next up you need to create a configuration class ```MyConfiguration```.
-The class needs to be marked with a `@Configuration` annotation.
+First, you need to create a configuration class, an example of which you can see below.
+To operate as a configuration class it needs to be marked with a `@Configuration` annotation.
 
 ```php
 <?php
@@ -44,3 +36,23 @@ class MyConfiguration
 {
 }
 ```
+
+### Bootstrap Disco
+
+Next, you need to bootstrap disco.
+To do so, use the following code in your bootstrapping logic.
+
+```php
+<?php
+
+use \bitExpert\Disco\{
+  AnnotationBeanFactory,
+  BeanFactoryRegistry
+}
+
+$beanFactory = new AnnotationBeanFactory(MyConfiguration::class);
+BeanFactoryRegistry::register($beanFactory);
+```
+
+This creates a `\bitExpert\Disco\AnnotationBeanFactory` instance and registers it with the `\bitExpert\Disco\BeanFactoryRegistry`.
+This is necessary because Disco needs to retrieve the active container instance in several locations where it does not have access to the container instance itself.

docs/intro/what-is-disco.md

@@ -5,17 +5,13 @@ annotation-based dependency injection container.
 
 ## Why Disco?
 
-Instead of using XML, YAML, or JSON Disco uses PHP code - specifically a
-PHP class - to define objects and their dependencies.
+Instead of using _XML_, _YAML_, or _JSON_, Disco uses PHP code, specifically a PHP class, to define both objects and their dependencies.
 
 Using PHP code as a configuration language has the following advantages:
 - Relies on the language the developer knows best
 - No need to "compile" the configuration to determine if it is "correct" or not
-- The developer can rely on the same refactoring features of their IDE for the configuration as for the code.
-- The developer can rely on the same auto-complete features of their IDE for the configuration as for the code.
+- The developer can rely on the same refactoring features of their IDE (or text editor) for the configuration as for the code.
+- The developer can depend on the same auto-complete features of their IDE for the configuration as for the code.
+
+Several other DI containers in PHP also rely on PHP code for configuring dependencies. What makes Disco unique in its design is that it enforces the usage of typed dependencies everywhere in the configuration code. Doing so helps developers to spot type errors right where they happen, assuming a sophisticated IDE is used.
 
-There a a few other DI containers in PHP that also rely on PHP code to
-configure the dependencies. What makes Disco unique in its design is that
-it enforces the usage of typed dependencies everywhere in the configuration
-code. This helps a developer to spot type errors right where they happen
-given a sophisticated IDE is used.