Small fixes

quick_start.rst

@@ -283,8 +283,10 @@ in our case) and tell Behat that this code represents a specific scenario step
 .. note::
 
     Behat uses PHP Attributes for step definitions, step
-    transformations and hooks. It can also use doc-block annotations
-    and this will be described in the User Guide
+    transformations and hooks. It also supports doc-block
+    annotations for compatibility with legacy code, but this
+    syntax is deprecated - see the :doc:`annotations </user_guide/annotations>` documentation
+    for details.
 
 ``#[Given('there is a(n) :arg1, which costs £:arg2')]`` above the method tells Behat
 that this particular method should be executed whenever Behat sees step that

user_guide/annotations.rst

@@ -2,8 +2,8 @@ Annotations
 ===========
 
 Historically Behat used doc-block annotations instead of attributes to define steps, hooks and
-transformations in PHP contexts. These annotations are still available and you can use them instead
-of PHP attributes in your projects.
+transformations in PHP contexts. These annotations are still available for now, and you can use them instead
+of PHP attributes in your projects - however they will likely be deprecated and removed in the future.
 
 Step Annotations
 ----------------
@@ -27,9 +27,9 @@ Here is an example of how you can define your steps using annotations:
         }
 
         /*
-         * @When event occurs
+         * @When an :event occurs
          */
-        public function doSomeAction()
+        public function onEvent(string $event)
         {
             // do something
         }
@@ -102,11 +102,11 @@ Existing code
 -------------
 
 Even though annotations are still available, they will probably be deprecated and eventually removed in the future.
-In this way, for new projects we recommend that you don't use them. If your current project uses annotations, we
+Therefore, we do not recommend using annotations for new projects. If your current project uses annotations, we
 recommend that you refactor your code to use PHP attributes instead. This can be done manually but you should be able
 to use the search and replace capabilities of your IDE to do this in a more automated way.
 
-Alternatively you may want to use a tool like `Rector`_ which can do automated refactoring of your code. Rector includes
+Alternatively you may want to use a tool like `Rector`_ which can do automated refactoring of your code. Rector 2.0 includes
 a rule that allows you to automatically convert any doc-block annotations to the corresponding attributes.
 To use it for your Behat contexts, add the following option to your Rector configuration: