diff --git a/core/serialization.md b/core/serialization.md
index 030e031116c..e4e21650b62 100644
--- a/core/serialization.md
+++ b/core/serialization.md
@@ -8,12 +8,12 @@ The main serialization process has two stages:
 
 ![Serializer workflow](images/SerializerWorkflow.png)
 
-> As you can see in the picture above, an array is used as a man in the middle. This way, Encoders will only deal with turning specific formats into arrays and vice versa. The same way, Normalizers will deal with turning specific objects into arrays and vice versa.
+> As you can see in the picture above, an array is used as a man-in-the-middle. This way, Encoders will only deal with turning specific formats into arrays and vice versa. The same way, Normalizers will deal with turning specific objects into arrays and vice versa.
 -- [The Symfony documentation](https://symfony.com/doc/current/components/serializer.html)
 
 Unlike Symfony itself, API Platform leverages custom normalizers, its router and the [data provider](data-providers.md) system to do an advanced transformation. Metadata are added to the generated document including links, type information, pagination data or available filters.
 
-The API Platform Serializer is extendable, you can register custom normalizers and encoders to support other formats. You can also decorate existing normalizers to customize their behaviors.
+The API Platform Serializer is extendable. You can register custom normalizers and encoders in order to support other formats. You can also decorate existing normalizers to customize their behaviors.
 
 ## Available Serializers
 
@@ -30,21 +30,19 @@ JSON-LD, or JavaScript Object Notation for Linked Data, is a method of encoding
 
 ## The Serialization Context, Groups and Relations
 
-API Platform allows to specify the `$context` parameter used by the Symfony Serializer. This context has a handy
-`groups` key allowing to choose which attributes of the resource are exposed during the normalization (read) and denormalization
-(write) process.
+API Platform allows you to specify the `$context` variable used by the Symfony Serializer. This variable is an associative array that has a handy `groups` key allowing you to choose which attributes of the resource are exposed during the normalization (read) and denormalization (write) processes.
 It relies on the [serialization (and deserialization) groups](https://symfony.com/doc/current/components/serializer.html#attributes-groups)
 feature of the Symfony Serializer component.
 
-In addition to groups, you can use any option supported by the Symfony Serializer such as [`enable_max_depth`](https://symfony.com/doc/current/components/serializer.html#handling-serialization-depth)
+In addition to groups, you can use any option supported by the Symfony Serializer. For example, you can use [`enable_max_depth`](https://symfony.com/doc/current/components/serializer.html#handling-serialization-depth)
 to limit the serialization depth.
 
 ### Configuration
 
-Just like other Symfony and API Platform components, the Serializer can be configured using annotations, XML and YAML.
-As annotations are easy to understand and allow to group code and configuration, we will use them in the following examples.
+Just like other Symfony and API Platform components, the Serializer component can be configured using annotations, XML or YAML.
+Since annotations are easy to understand, we will use them in the following examples.
 
-However, if you don't use the official distribution of API Platform, don't forget to enable annotation support in the serializer
+Note: if you aren't using the official distribution of API Platform, you will need to enable annotation support in the serializer
 configuration:
 
 ```yaml
@@ -58,7 +56,10 @@ all set!
 
 ## Using Serialization Groups
 
-It is really simple to specify what groups to use in the API system:
+It is simple to specify what groups to use in the API system:
+
+1. Add the `normalizationContext` and `denormalizationContext` annotation properties to the `@ApiResource` annotation, and specify which groups to use. Here you see that we add `read` and `write`, respectively.  You can use any group names you wish.
+2. Apply the `@Groups` annotation to properties in the object.
 
 ```php
 <?php
@@ -91,7 +92,7 @@ class Book
 }
 ```
 
-Alternatively, you can use the verbose syntax that is strictly equivalent:
+Alternatively, you can use the more verbose syntax:
 
 ```php
 <?php
@@ -105,21 +106,23 @@ Alternatively, you can use the verbose syntax that is strictly equivalent:
  */
 ```
 
-With the config of the previous examples, the `name` property will be accessible in read and write, but the `author` property
-will be write only, therefore the `author` property will never be included in documents returned by the API.
+In the previous example, the `name` property will be visible when reading (`GET`) the object, and it will also be available
+to write (`PUT/POST`).  The `author` property will be write-only; it will not be visible when serialized responses are 
+returned by the API.
+
+Internally, API Platform passes the value of the `normalization_context` to the Symfony Serializer during the normalization
+process; `denormalization_context` is passed during denormalization (writing).
 
-The value of the `normalization_context` is passed to the Symfony Serializer during the normalization process. In the same
-way, `denormalization_context` is used for denormalization.
-You can configure groups as well as any Symfony Serializer option configurable through the context argument (e.g. the `enable_max_depth`
-key when using [the `@MaxDepth` annotation](https://symfony.com/doc/current/components/serializer.html#handling-serialization-depth)).
+In addition to the `groups` key, you can configure any Symfony Serializer option through the `$context` parameter
+(e.g. the `enable_max_depth`key when using [the `@MaxDepth` annotation](https://symfony.com/doc/current/components/serializer.html#handling-serialization-depth)).
 
-Built-in actions and the Hydra documentation generator will leverage the specified serialization and deserialization groups
-to give access only to exposed properties and to guess if they are readable and/or writable.
+Any serialization and deserialization groups that you specify will also be leveraged by the built-in actions and the Hydra
+documentation generator.
 
-## Using Different Serialization Groups per Operation
+## Using Serialization Groups per Operation
 
-It is possible to specify normalization and denormalization contexts (as well as any other attribute) on a per operation
-basis. API Platform will always use the most specific definition. For instance if normalization groups are set both
+It is possible to specify normalization and denormalization contexts (as well as any other attribute) on a per-operation
+basis. API Platform will always use the most specific definition. For instance, if normalization groups are set both
 at the resource level and at the operation level, the configuration set at the operation level will be used and the resource
 level ignored.
 
@@ -161,16 +164,16 @@ class Book
 }
 ```
 
-`name` and `author` properties will be included in the document generated during a `GET` operation because the configuration
+The `name` and `author` properties will be included in the document generated during a `GET` operation because the configuration
 defined at the resource level is inherited. However the document generated when a `PUT` request will be received will only
 include the `name` property because of the specific configuration for this operation.
 
-Refer to the documentation of [operations](operations.md) to learn more about the concept of operations.
+Refer to the [operations](operations.md) documentation to learn more.
 
 ### Embedding Relations
 
-By default, the serializer provided with API Platform represents relations between objects by [dereferenceables IRIs](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier).
-They allow to retrieve details of related objects by issuing an extra HTTP request.
+By default, the serializer provided with API Platform represents relations between objects using [dereferenceables IRIs](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier).
+They allow you to retrieve details for related objects by issuing extra HTTP requests.
 
 In the following JSON document, the relation from a book to an author is represented by an URI:
 
@@ -184,12 +187,10 @@ In the following JSON document, the relation from a book to an author is represe
 }
 ```
 
-### Normalization
-
-To improve the application's performance, it is sometimes necessary to avoid issuing extra HTTP requests. It is possible
-to embed related objects (or only some of their properties) directly in the parent response through serialization groups.
-By using the following serialization groups annotations (`@Groups`), a JSON representation of the author is embedded in
-the book response:
+However, for performance reasons, it is sometimes prerable to avoid forcing the client to issue extra HTTP requests. 
+It is possible to embed related objects (in their entirity, or only some of their properties) directly in the parent 
+response through the use of serialization groups. By using the following serialization groups annotations (`@Groups`), 
+a JSON representation of the author is embedded in the book response:
 
 ```php
 <?php
@@ -243,7 +244,7 @@ class Person
 }
 ```
 
-The generated JSON with previous settings will be like the following:
+The generated JSON using previous settings is below:
 
 ```json
 {
@@ -260,13 +261,13 @@ The generated JSON with previous settings will be like the following:
 ```
 
 In order to optimize such embedded relations, the default Doctrine data provider will automatically join entities on relations
-marked as [`EAGER`](http://doctrine-orm.readthedocs.io/projects/doctrine-orm/en/latest/reference/annotations-reference.html#manytoone)
-avoiding extra queries to be executed when serializing the sub-objects.
+marked as [`EAGER`](http://doctrine-orm.readthedocs.io/projects/doctrine-orm/en/latest/reference/annotations-reference.html#manytoone).
+This avoids the need for extra queries to be executed when serializing the related objects.
 
 ### Denormalization
 
-It is also possible to embed a relation in `PUT` and `POST` requests. To enable that feature, the serialization groups must be
-set the same way as normalization and the configuration should be like this:
+It is also possible to embed a relation in `PUT` and `POST` requests. To enable that feature, set the serialization groups
+the same way as normalization. For example:
 
 ```php
 <?php
@@ -287,15 +288,15 @@ class Book
 
 The following rules apply when denormalizating embedded relations:
 
-* If a `@id` key is present in the embedded resource, the object corresponding to the given URI will be retrieved through
-the data provider and any changes in the embedded relation will be applied to that object.
+* If an `@id` key is present in the embedded resource, then the object corresponding to the given URI will be retrieved through
+the data provider. Any changes in the embedded relation will also be applied to that object.
 * If no `@id` key exists, a new object will be created containing data provided in the embedded JSON document.
 
-You can create as many relation embedding levels as you want.
+You can specify as many embedded relation levels as you want.
 
 ## Changing the Serialization Context Dynamically
 
-Let's imagine a resource where most fields can be managed by any user, but some can be managed by admin users only:
+Let's imagine a resource where most fields can be managed by any user, but some can be managed only by admin users:
 
 ```php
 <?php
@@ -317,7 +318,7 @@ class Book
     // ...
 
     /**
-     * This field can be managed by an admin only
+     * This field can be managed only by an admin
      *
      * @var bool
      *
@@ -338,8 +339,8 @@ class Book
 }
 ```
 
-All entry points are the same for all users, so we should find a way to detect if authenticated user is admin, and if so
-dynamically add `admin:input` to deserialization groups.
+All entry points are the same for all users, so we should find a way to detect if authenticated user is an admin, and if so
+dynamically add `admin:input` value to deserialization groups in the `$context` array.
 
 API Platform implements a `ContextBuilder`, which prepares the context for serialization & deserialization. Let's
 [decorate this service](http://symfony.com/doc/current/service_container/service_decoration.html) to override the
@@ -391,12 +392,19 @@ final class BookContextBuilder implements SerializerContextBuilderInterface
 }
 ```
 
-If the user has `ROLE_ADMIN` permission and the subject is an instance of Book, `admin_input` group will be dynamically added to the denormalization context.
-The variable `$normalization` lets you check whether the context is for normalization (if true) or denormalization.
+If the user has the `ROLE_ADMIN` permission and the subject is an instance of Book, `admin_input` group will be dynamically added to the 
+denormalization context.  The `$normalization` variable lets you check whether the context is for normalization (if `TRUE`) or denormalization 
+(`FALSE`).
 
-## Changing the Serialization Context on a Per Item Basis
+## Changing the Serialization Context on a Per-item Basis
 
-The example above shows how you can modify the normalization/denormalization context based on the current user permissions for all the books that are being normalized/denormalized. Sometimes, however, the permissions vary depending on what book is being processed. Think of ACL's: User A may retrieve Book A but not Book B. In that case, we have to leverage the power of the Symfony Serializer and register our own normalizer that adds the group on every single item (priority `64` is just an example, make sure your normalizer gets loaded first):
+The example above demonstrates how you can modify the normalization/denormalization context based on the current user 
+permissions for all books. Sometimes, however, the permissions vary depending on what book is being processed.
+
+Think of ACL's: User "A" may retrieve Book "A" but not Book "B". In this case, we need to leverage the power of the 
+Symfony Serializer and register our own normalizer that adds the group on every single item (note: priority `64` is 
+an example; it is always important to make sure your normalizer gets loaded first, so set the priority to whatever value
+is appropriate for your application; higher values are loaded earlier):
 
 ```yaml
 # api/config/services.yaml
@@ -407,7 +415,10 @@ services:
             - { name: 'serializer.normalizer', priority: 64 }
 ```
 
-The Normalizer class is a bit harder to understand because it has to make sure there's no recursion. To do so, it has to be aware of the Serializer instance itself to pass on the object to normalize to the other normalizers once it added the groups. Here's how this could look like:
+The Normalizer class is a bit harder to understand, because it must ensure that it is only called once and that there is no recursion. 
+To accomplish this, it needs to be aware of the Serializer instance itself.
+
+Here is an example:
 
 ```php
 <?php
@@ -467,9 +478,11 @@ class BookAttributeNormalizer implements ContextAwareNormalizerInterface, Serial
 }
 ```
 
-This will add the serialization group `can_retrieve_book` only if the currently logged in user has access to the given book instance.
+This will add the serialization group `can_retrieve_book` only if the currently logged-in user has access to the given book 
+instance.
 
-Note: In this example, we use the `TokenStorageInterface` to check for access. Don't forget that Symfony provides many useful other services that might be better suited depending on your use case such as the [`AuthorizationChecker`](https://symfony.com/doc/current/components/security/authorization.html#authorization-checker)
+Note: In this example, we use the `TokenStorageInterface` to verify access to the book instance.  However, Symfony 
+provides many useful other services that might be better suited to your use case.  For example, the [`AuthorizationChecker`](https://symfony.com/doc/current/components/security/authorization.html#authorization-checker).
 
 ## Name Conversion
 
@@ -490,10 +503,10 @@ api_platform:
     name_converter: 'Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter'
 ```
 
-## Decorating a Serializer and Add Extra Data
+## Decorating a Serializer and Adding Extra Data
 
-In the following example, we will see how we add extra informations to the output.
-Here is how we add the date on each request in `GET`:
+In the following example, we will see how we add extra informations to the serialized output.  Here is how we add the 
+date on each request in `GET`:
 
 ```yaml
 # api/config/services.yaml
@@ -566,44 +579,58 @@ final class ApiNormalizer implements NormalizerInterface, DenormalizerInterface,
 API Platform is able to guess the entity identifier using [Doctrine metadata](http://doctrine-orm.readthedocs.org/en/latest/reference/basic-mapping.html#identifiers-primary-keys).
 It also supports composite identifiers.
 
-If Doctrine ORM is not used, the identifier must be marked explicitly using the `identifier` attribute of the `ApiPlatform\Core\Annotation\ApiProperty`
-annotation.
+If you are not using the Doctrine ORM Provider, you must explictely mark the identifier using the `identifier` attribute of
+the `ApiPlatform\Core\Annotation\ApiProperty` annotation.  For example:
 
-In some cases, you will want to set the identifier of a resource from the client (e.g. a client-side generated UUID, or a slug).
-In this case the identifier property must become a writable class property.
-
-To do this you simply have to:
 
-* Create a setter for the identifier of the entity or make it a `public` property
-* Add the denormalization group to the property if you use a specific denormalization group
-* If you use Doctrine ORM, be sure to **not** mark this property with [the `@GeneratedValue` annotation](http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#identifier-generation-strategies)
-  or use the `NONE` value
+```php
+/**
+ * @ApiResource()
+ */
+class Book
+{
+    // ...
+    
+    /**
+     * @ApiProperty(identifier=true)
+     */
+    private $id;
 
-## Embedding the JSON-LD Context
+    /**
+     * This field can be managed only by an admin
+     *
+     * @var bool
+     */
+    private $active = false;
 
-By default, the generated [JSON-LD context](https://www.w3.org/TR/json-ld/#the-context) (`@context`) is only reference by
-an IRI. A client supporting JSON-LD must send a second HTTP request to retrieve it:
+    /**
+     * This field can be managed by any user
+     *
+     * @var string
+     */
+    private $name;
 
-```json
-{
-  "@context": "/contexts/Book",
-  "@id": "/books/62",
-  "@type": "Book",
-  "name": "My awesome book",
-  "author": "/people/59"
+    // ...
 }
 ```
 
-You can configure API Platform to embed the JSON-LD context in the root document like the following:
+In some cases, you will want to set the identifier of a resource from the client (e.g. a client-side generated UUID, or a slug).
+In such cases, you must make the identifier property a writable class property.  Specifically, to use client-generated IDs, you 
+must do the following:
+
+1. create a setter for the identifier of the entity (e.g. `public function setId(string $id)`) or make it a `public` property ,
+2. add the denormalization group to the property (only if you use a specific denormalization group), and,
+3. if you use Doctrine ORM, be sure to **not** mark this property with [the `@GeneratedValue` annotation](http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/basic-mapping.html#identifier-generation-strategies)
+  or use the `NONE` value
+
+## Embedding the JSON-LD Context
+
+By default, the generated [JSON-LD context](https://www.w3.org/TR/json-ld/#the-context) (`@context`) is only referenced by
+an IRI. A client that uses JSON-LD must send a second HTTP request to retrieve it:
 
 ```json
 {
-  "@context": {
-    "@vocab": "http://localhost:8000/apidoc#",
-    "hydra": "http://www.w3.org/ns/hydra/core#",
-    "name": "http://schema.org/name",
-    "author": "http://schema.org/author"
-  },
+  "@context": "/contexts/Book",
   "@id": "/books/62",
   "@type": "Book",
   "name": "My awesome book",
@@ -611,7 +638,8 @@ You can configure API Platform to embed the JSON-LD context in the root document
 }
 ```
 
-To do so, use the following configuration:
+You can configure API Platform to embed the JSON-LD context in the root document like the by adding the `jsonld_embed_context`
+attribute to the `@ApiResource` annotation:
 
 ```php
 <?php
@@ -629,3 +657,20 @@ class Book
     // ...
 }
 ```
+
+The JSON output will now include the embedded context:
+
+```json
+{
+  "@context": {
+    "@vocab": "http://localhost:8000/apidoc#",
+    "hydra": "http://www.w3.org/ns/hydra/core#",
+    "name": "http://schema.org/name",
+    "author": "http://schema.org/author"
+  },
+  "@id": "/books/62",
+  "@type": "Book",
+  "name": "My awesome book",
+  "author": "/people/59"
+}
+```