diff --git a/components/workflow.rst b/components/workflow.rst
index 54db794696a..029b0d7dfe5 100644
--- a/components/workflow.rst
+++ b/components/workflow.rst
@@ -32,28 +32,30 @@ a ``Definition`` and a way to write the states to the objects (i.e. an
 instance of a :class:`Symfony\\Component\\Workflow\\MarkingStore\\MarkingStoreInterface`).
 
 Consider the following example for a blog post. A post can have one of a number
-of predefined statuses (`draft`, `review`, `rejected`, `published`). In a workflow,
+of predefined statuses (`draft`, `reviewed`, `rejected`, `published`). In a workflow,
 these statuses are called **places**. You can define the workflow like this::
 
     use Symfony\Component\Workflow\DefinitionBuilder;
-    use Symfony\Component\Workflow\MarkingStore\SingleStateMarkingStore;
+    use Symfony\Component\Workflow\MarkingStore\MethodMarkingStore;
     use Symfony\Component\Workflow\Transition;
     use Symfony\Component\Workflow\Workflow;
 
     $definitionBuilder = new DefinitionBuilder();
-    $definition = $definitionBuilder->addPlaces(['draft', 'review', 'rejected', 'published'])
+    $definition = $definitionBuilder->addPlaces(['draft', 'reviewed', 'rejected', 'published'])
         // Transitions are defined with a unique name, an origin place and a destination place
-        ->addTransition(new Transition('to_review', 'draft', 'review'))
-        ->addTransition(new Transition('publish', 'review', 'published'))
-        ->addTransition(new Transition('reject', 'review', 'rejected'))
+        ->addTransition(new Transition('to_review', 'draft', 'reviewed'))
+        ->addTransition(new Transition('publish', 'reviewed', 'published'))
+        ->addTransition(new Transition('reject', 'reviewed', 'rejected'))
         ->build()
     ;
 
-    $marking = new SingleStateMarkingStore('currentState');
+    $singleState = true; // true if the subject can be in only one state at a given time
+    $property = 'currentState' // subject property name where the state is stored
+    $marking = new MethodMarkingStore($singleState, $property);
     $workflow = new Workflow($definition, $marking);
 
-The ``Workflow`` can now help you to decide what actions are allowed
-on a blog post depending on what *place* it is in. This will keep your domain
+The ``Workflow`` can now help you to decide what *transitions* (actions) are allowed
+on a blog post depending on what *place* (state) it is in. This will keep your domain
 logic in one place and not spread all over your application.
 
 When you define multiple workflows you should consider using a ``Registry``,
@@ -66,11 +68,11 @@ are trying to use it with::
     use Symfony\Component\Workflow\Registry;
     use Symfony\Component\Workflow\SupportStrategy\InstanceOfSupportStrategy;
 
-    $blogWorkflow = ...
+    $blogPostWorkflow = ...
     $newsletterWorkflow = ...
 
     $registry = new Registry();
-    $registry->addWorkflow($blogWorkflow, new InstanceOfSupportStrategy(BlogPost::class));
+    $registry->addWorkflow($blogPostWorkflow, new InstanceOfSupportStrategy(BlogPost::class));
     $registry->addWorkflow($newsletterWorkflow, new InstanceOfSupportStrategy(Newsletter::class));
 
 Usage
@@ -80,17 +82,17 @@ When you have configured a ``Registry`` with your workflows,
 you can retrieve a workflow from it and use it as follows::
 
     // ...
-    // Consider that $post is in state "draft" by default
-    $post = new BlogPost();
-    $workflow = $registry->get($post);
+    // Consider that $blogPost is in place "draft" by default
+    $blogPost = new BlogPost();
+    $workflow = $registry->get($blogPost);
 
-    $workflow->can($post, 'publish'); // False
-    $workflow->can($post, 'to_review'); // True
+    $workflow->can($blogPost, 'publish'); // False
+    $workflow->can($blogPost, 'to_review'); // True
 
-    $workflow->apply($post, 'to_review'); // $post is now in state "review"
+    $workflow->apply($blogPost, 'to_review'); // $blogPost is now in place "reviewed"
 
-    $workflow->can($post, 'publish'); // True
-    $workflow->getEnabledTransitions($post); // ['publish', 'reject']
+    $workflow->can($blogPost, 'publish'); // True
+    $workflow->getEnabledTransitions($blogPost); // $blogPost can perform transition "publish" or "reject"
 
 Learn more
 ----------