diff --git a/components/workflow.rst b/components/workflow.rst
index 137695ddb0f..de936fa5baa 100644
--- a/components/workflow.rst
+++ b/components/workflow.rst
@@ -79,10 +79,11 @@ Usage
 -----
 
 When you have configured a ``Registry`` with your workflows,
-you can retrieve a workflow from it and use it as follows::
+you can retreive a workflow from it and use it as follows::
 
     // ...
     // Consider that $blogPost is in place "draft" by default
+    // Consider that $post is in state "draft" by default
     $blogPost = new BlogPost();
     $workflow = $registry->get($blogPost);
 
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
index c03cc8500c7..08f55dcf2a7 100644
--- a/reference/configuration/framework.rst
+++ b/reference/configuration/framework.rst
@@ -255,8 +255,9 @@ Configuration
   * :ref:`name <reference-workflows-name>`
 
     * `audit_trail`_
-    * `initial_place`_
+    * `initial_marking`_
     * `marking_store`_
+    * `metadata`_
     * `places`_
     * `supports`_
     * `support_strategy`_
@@ -2736,12 +2737,12 @@ audit_trail
 If set to ``true``, the :class:`Symfony\\Component\\Workflow\\EventListener\\AuditTrailListener`
 will be enabled.
 
-initial_place
-"""""""""""""
+initial_marking
+"""""""""""""""
 
-**type**: ``string`` **default**: ``null``
+**type**: ``string`` | ``array``
 
-One of the ``places`` or ``null``. If not null and the supported object is not
+One of the ``places`` or ``empty``. If not null and the supported object is not
 already initialized via the workflow, this place will be set.
 
 marking_store
@@ -2753,8 +2754,16 @@ Each marking store can define any of these options:
 
 * ``arguments`` (**type**: ``array``)
 * ``service`` (**type**: ``string``)
-* ``type`` (**type**: ``string`` **possible values**: ``'multiple_state'`` or
-  ``'single_state'``)
+* ``type`` (**type**: ``string`` **allow value**: ``'method'``)
+
+metadata
+""""""""
+
+**type**: ``array``
+
+Metadata available for the workflow configuration.
+Note that ``places`` and ``transitions`` can also have their own
+``metadata`` entry.
 
 places
 """"""
diff --git a/workflow.rst b/workflow.rst
index cf1a5802036..f477ace9665 100644
--- a/workflow.rst
+++ b/workflow.rst
@@ -54,12 +54,12 @@ like this:
                     audit_trail:
                         enabled: true
                     marking_store:
-                        type: 'multiple_state' # or 'single_state'
-                        arguments:
+                        type: 'method'
+                        property:
                             - 'currentPlace'
                     supports:
                         - App\Entity\BlogPost
-                    initial_place: draft
+                    initial_marking: draft
                     places:
                         - draft
                         - reviewed
@@ -90,35 +90,28 @@ like this:
             <framework:config>
                 <framework:workflow name="blog_publishing" type="workflow">
                     <framework:audit-trail enabled="true"/>
-
                     <framework:marking-store type="single_state">
                         <framework:argument>currentPlace</framework:argument>
                     </framework:marking-store>
-
                     <framework:support>App\Entity\BlogPost</framework:support>
-
+                    <framework:initial-marking>draft</framework:initial-marking>
                     <framework:place>draft</framework:place>
                     <framework:place>reviewed</framework:place>
                     <framework:place>rejected</framework:place>
                     <framework:place>published</framework:place>
-
                     <framework:transition name="to_review">
                         <framework:from>draft</framework:from>
                         <framework:to>reviewed</framework:to>
                     </framework:transition>
-
                     <framework:transition name="publish">
                         <framework:from>reviewed</framework:from>
                         <framework:to>published</framework:to>
                     </framework:transition>
-
                     <framework:transition name="reject">
                         <framework:from>reviewed</framework:from>
                         <framework:to>rejected</framework:to>
                     </framework:transition>
-
                 </framework:workflow>
-
             </framework:config>
         </container>
 
@@ -134,10 +127,11 @@ like this:
                         'enabled' => true
                     ],
                     'marking_store' => [
-                        'type' => 'multiple_state', // or 'single_state'
-                        'arguments' => ['currentPlace']
+                        'type' => 'method'
+                        'property' => ['currentPlace']
                     ],
                     'supports' => ['App\Entity\BlogPost'],
+                    'initial_marking' => 'draft',
                     'places' => [
                         'draft',
                         'reviewed',
@@ -177,18 +171,6 @@ As configured, the following property is used by the marking store::
         public $content;
     }
 
-.. note::
-
-    The marking store type could be "multiple_state" or "single_state". A single
-    state marking store does not support a model being on multiple places at the
-    same time.
-
-.. tip::
-
-    The ``type`` (default value ``single_state``) and ``arguments`` (default
-    value ``marking``) attributes of the ``marking_store`` option are optional.
-    If omitted, their default values will be used.
-
 .. tip::
 
     Setting the ``audit_trail.enabled`` option to ``true`` makes the application
@@ -200,7 +182,7 @@ what actions are allowed on a blog post::
     use App\Entity\BlogPost;
     use Symfony\Component\Workflow\Exception\LogicException;
 
-    $post = BlogPost();
+    $post = new BlogPost();
 
     $workflow = $this->container->get('workflow.blog_publishing');
     $workflow->can($post, 'publish'); // False
@@ -630,8 +612,8 @@ requires:
                         <framework:from>reviewed</framework:from>
                         <framework:to>published</framework:to>
                         <framework:metadata>
-                            <framework:hour_limit>20</framework:priority>
-                            <framework:explanation>You can not publish after 8 PM.</framework:priority>
+                            <framework:hour_limit>20</framework:hour_limit>
+                            <framework:explanation>You can not publish after 8 PM.</framework:explanation>
                         </framework:metadata>
                     </framework:transition>
                 </framework:workflow>
@@ -682,6 +664,7 @@ Then you can access this metadata in your controller as follows::
 
     use App\Entity\BlogPost;
     use Symfony\Component\Workflow\Registry;
+    use App\Entity\BlogPost;
 
     public function myController(Registry $registry, BlogPost $post)
     {
diff --git a/workflow/dumping-workflows.rst b/workflow/dumping-workflows.rst
index 78a2d566606..2499dd35225 100644
--- a/workflow/dumping-workflows.rst
+++ b/workflow/dumping-workflows.rst
@@ -228,63 +228,63 @@ Below is the configuration for the pull request state machine with styling added
             // ...
             'workflows' => [
                 'pull_request' => [
-                  'type' => 'state_machine',
-                  'supports' => ['App\Entity\PullRequest'],
-                  'places' => [
-                    'start',
-                    'coding',
-                    'test',
-                    'review' => [
-                        'metadata' => [
-                            'description' => 'Human review',
+                    'type' => 'state_machine',
+                    'supports' => ['App\Entity\PullRequest'],
+                    'places' => [
+                        'start',
+                        'coding',
+                        'test',
+                        'review' => [
+                          'metadata' => [
+                              'description' => 'Human review',
+                          ],
                         ],
-                    ],
-                    'merged',
-                    'closed' => [
-                        'metadata' => [
-                            'bg_color' => 'DeepSkyBlue',
+                        'merged',
+                        'closed' => [
+                          'metadata' => [
+                              'bg_color' => 'DeepSkyBlue',
+                          ],
                         ],
                     ],
-                  ],
-                  'transitions' => [
-                    'submit'=> [
-                      'from' => 'start',
-                      'to' => 'test',
-                    ],
-                    'update'=> [
-                      'from' => ['coding', 'test', 'review'],
-                      'to' => 'test',
-                      'metadata' => [
-                        'arrow_color' => 'Turquoise',
-                      ],
-                    ],
-                    'wait_for_review'=> [
-                      'from' => 'test',
-                      'to' => 'review',
-                      'metadata' => [
-                        'color' => 'Orange',
-                      ],
-                    ],
-                    'request_change'=> [
-                      'from' => 'review',
-                      'to' => 'coding',
-                    ],
-                    'accept'=> [
-                      'from' => 'review',
-                      'to' => 'merged',
-                      'metadata' => [
-                        'label' => 'Accept PR',
-                      ],
-                    ],
-                    'reject'=> [
-                      'from' => 'review',
-                      'to' => 'closed',
-                    ],
-                    'reopen'=> [
-                      'from' => 'start',
-                      'to' => 'review',
+                    'transitions' => [
+                        'submit'=> [
+                            'from' => 'start',
+                            'to' => 'test',
+                        ],
+                        'update'=> [
+                            'from' => ['coding', 'test', 'review'],
+                            'to' => 'test',
+                            'metadata' => [
+                                'arrow_color' => 'Turquoise',
+                            ],
+                        ],
+                        'wait_for_review'=> [
+                            'from' => 'test',
+                            'to' => 'review',
+                            'metadata' => [
+                                'color' => 'Orange',
+                            ],
+                        ],
+                        'request_change'=> [
+                            'from' => 'review',
+                            'to' => 'coding',
+                        ],
+                        'accept'=> [
+                            'from' => 'review',
+                            'to' => 'merged',
+                            'metadata' => [
+                                'label' => 'Accept PR',
+                            ],
+                        ],
+                        'reject'=> [
+                            'from' => 'review',
+                            'to' => 'closed',
+                        ],
+                        'reopen'=> [
+                            'from' => 'start',
+                            'to' => 'review',
+                        ],
                     ],
-                  ],
                 ],
             ],
         ]);
diff --git a/workflow/introduction.rst b/workflow/introduction.rst
index c8302870ac1..385ec8e8cd1 100644
--- a/workflow/introduction.rst
+++ b/workflow/introduction.rst
@@ -79,7 +79,7 @@ Below is the configuration for the pull request state machine.
                     type: 'state_machine'
                     supports:
                         - App\Entity\PullRequest
-                    initial_place: start
+                    initial_marking: start
                     places:
                         - start
                         - coding
@@ -190,46 +190,46 @@ Below is the configuration for the pull request state machine.
             // ...
             'workflows' => [
                 'pull_request' => [
-                  'type' => 'state_machine',
-                  'supports' => ['App\Entity\PullRequest'],
-                  'places' => [
-                    'start',
-                    'coding',
-                    'test',
-                    'review',
-                    'merged',
-                    'closed',
-                  ],
-                  'transitions' => [
-                    'submit'=> [
-                      'from' => 'start',
-                      'to' => 'test',
+                    'type' => 'state_machine',
+                    'supports' => ['App\Entity\PullRequest'],
+                    'places' => [
+                        'start',
+                        'coding',
+                        'test',
+                        'review',
+                        'merged',
+                        'closed',
                     ],
-                    'update'=> [
-                      'from' => ['coding', 'test', 'review'],
-                      'to' => 'test',
+                    'transitions' => [
+                        'submit'=> [
+                            'from' => 'start',
+                            'to' => 'test',
+                        ],
+                        'update'=> [
+                            'from' => ['coding', 'test', 'review'],
+                            'to' => 'test',
+                        ],
+                        'wait_for_review'=> [
+                            'from' => 'test',
+                            'to' => 'review',
+                        ],
+                        'request_change'=> [
+                            'from' => 'review',
+                            'to' => 'coding',
+                        ],
+                        'accept'=> [
+                            'from' => 'review',
+                            'to' => 'merged',
+                        ],
+                        'reject'=> [
+                            'from' => 'review',
+                            'to' => 'closed',
+                        ],
+                        'reopen'=> [
+                            'from' => 'start',
+                            'to' => 'review',
+                        ],
                     ],
-                    'wait_for_review'=> [
-                      'from' => 'test',
-                      'to' => 'review',
-                    ],
-                    'request_change'=> [
-                      'from' => 'review',
-                      'to' => 'coding',
-                    ],
-                    'accept'=> [
-                      'from' => 'review',
-                      'to' => 'merged',
-                    ],
-                    'reject'=> [
-                      'from' => 'review',
-                      'to' => 'closed',
-                    ],
-                    'reopen'=> [
-                      'from' => 'start',
-                      'to' => 'review',
-                    ],
-                  ],
                 ],
             ],
         ]);