1 files changed, 23 insertions, 15 deletions
diff --git a/qa/qa/page/README.md b/qa/qa/page/README.md
index dfad460a9a5..4d58f1a43b7 100644
--- a/qa/qa/page/README.md
+++ b/qa/qa/page/README.md
@@ -70,15 +70,15 @@ module Page
   module Main
     class Login < Page::Base
       view 'app/views/devise/passwords/edit.html.haml' do
-        element :password_field, 'password_field :password'
-        element :password_confirmation, 'password_field :password_confirmation'
-        element :change_password_button, 'submit "Change your password"'
+        element :password_field
+        element :password_confirmation
+        element :change_password_button
       end
 
       view 'app/views/devise/sessions/_new_base.html.haml' do
-        element :login_field, 'text_field :login'
-        element :password_field, 'password_field :password'
-        element :sign_in_button, 'submit "Sign in"'
+        element :login_field
+        element :password_field
+        element :sign_in_button
       end
 
       # ...
@@ -87,23 +87,31 @@ end
 ```
 
 The `view` DSL method declares the filename of the view where an
-`element` is implmented.
+`element` is implemented.
 
-The `element` DSL method in turn declares an element and defines a value
-to match to the actual view code. It is possible to use `element` with value,
-with a String value or with a Regexp.
+The `element` DSL method in turn declares an element for which a corresponding
+`qa-element-name-dasherized` CSS class need to be added to the view file.
+
+You can also define a value (String or Regexp) to match to the actual view
+code but **this is deprecated** in favor of the above method for two reasons:
+
+- Consistency: there is only one way to define an element
+- Separation of concerns: QA uses dedicated CSS classes instead of reusing code
+  or classes used by other components (e.g. `js-*` classes etc.)
 
 ```ruby
 view 'app/views/my/view.html.haml' do
+  # Implicitly require `.qa-logout-button` CSS class to be present in the view
+  element :logout_button
+
+  ## This is deprecated and forbidden by the `QA/ElementWithPattern` RuboCop cop.
   # Require `f.submit "Sign in"` to be present in `my/view.html.haml
-  element :my_button, 'f.submit "Sign in"'
+  element :my_button, 'f.submit "Sign in"' # rubocop:disable QA/ElementWithPattern
 
+  ## This is deprecated and forbidden by the `QA/ElementWithPattern` RuboCop cop.
   # Match every line in `my/view.html.haml` against
   # `/link_to .* "My Profile"/` regexp.
-  element :profile_link, /link_to .* "My Profile"/
-
-  # Implicitly require `.qa-logout-button` CSS class to be present in the view
-  element :logout_button
+  element :profile_link, /link_to .* "My Profile"/ # rubocop:disable QA/ElementWithPattern
 end
 ```