1 files changed, 53 insertions, 8 deletions
diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md
index 0272e1810f2..97560e616a1 100644
--- a/doc/development/testing_guide/end_to_end/style_guide.md
+++ b/doc/development/testing_guide/end_to_end/style_guide.md
@@ -45,7 +45,7 @@ Notice that in the above example, before clicking the `:operations_environments_
 
 > We can create these methods as helpers to abstract multi-step navigation.
 
-### Element naming convention
+## Element naming convention
 
 When adding new elements to a page, it's important that we have a uniform element naming convention.
 
@@ -63,17 +63,17 @@ We follow a simple formula roughly based on hungarian notation.
   - `_checkbox`
   - `_radio`
   - `_content`
-  
+
 *Note: This list is a work in progress. This list will eventually be the end-all enumeration of all available types.
         I.e., any element that does not end with something in this list is bad form.*
-  
-#### Examples
+
+### Examples
 
 **Good**
 
 ```ruby
 view '...' do
-  element :edit_button 
+  element :edit_button
   element :notes_tab
   element :squash_checkbox
   element :username_field
@@ -84,16 +84,61 @@ end
 **Bad**
 
 ```ruby
-view '...' do  
+view '...' do
   # `_confirmation` should be `_field`. what sort of confirmation? a checkbox confirmation? no real way to disambiguate.
   # an appropriate replacement would be `element :password_confirmation_field`
   element :password_confirmation
 
-  # `clone_options` is too vague. If it's a dropdown menu, it should be `clone_dropdown`. 
+  # `clone_options` is too vague. If it's a dropdown menu, it should be `clone_dropdown`.
   # If it's a checkbox, it should be `clone_checkbox`
   element :clone_options
-  
+
   # how is this url being displayed? is it a textbox? a simple span?
+  # If it is content on the page, it should be `ssh_clone_url_content`
   element :ssh_clone_url
 end
 ```
+
+## Block argument naming
+
+To have a standard on how we call pages when using the `.perform` method, we use the name of page object being called, all lowercased, and separated by underscore, if needed (see good and bad examples below.) This also applies to resources. We chose not to simply use `page` because that would shadow the Capybara DSL, potentially leading to confusion and bugs.
+
+### Examples
+
+**Good**
+
+```ruby
+# qa/specs/features/browser_ui/1_manage/project/add_project_member_spec.rb
+
+Page::Project::Settings::Members.perform do |members|
+  members.do_something
+end
+```
+
+```ruby
+# qa/specs/features/ee/browser_ui/3_create/merge_request/add_batch_comments_in_merge_request_spec.rb
+
+Resource::MergeRequest.fabricate! do |merge_request|
+  merge_request.do_something_else
+end
+```
+
+**Bad**
+
+```ruby
+# qa/specs/features/browser_ui/1_manage/project/add_project_member_spec.rb
+
+Page::Project::Settings::Members.perform do |project_settings_members_page|
+  project_settings_members_page.do_something
+end
+```
+
+```ruby
+# qa/specs/features/ee/browser_ui/3_create/merge_request/add_batch_comments_in_merge_request_spec.rb
+
+Resource::MergeRequest.fabricate! do |merge_request_page|
+  merge_request_page.do_something_else
+end
+```
+
+> Besides the advantage of having a standard in place, by following this standard we also write shorter lines of code.
+\ No newline at end of file