diff --git a/docs/source/api/commands/contains.md b/docs/source/api/commands/contains.md
index ea129805b6..94474b0c0a 100644
--- a/docs/source/api/commands/contains.md
+++ b/docs/source/api/commands/contains.md
@@ -4,51 +4,52 @@ comments: true
 description: ''
 ---
 
-Get the DOM element containing the text. DOM elements can contain *more* than the desired text and still match. Additionally, Cypress will prefer some DOM elements over the deepest element found.
+Get the DOM element containing the text. DOM elements can contain *more* than the desired text and still match. Additionally, Cypress will [prefer some DOM elements](#notes) over the deepest element found.
 
-**Preference order:**
+# Syntax
 
-- `input[type='submit']`
-- `button`
-- `a`
-- `label`
+```javascript
+cy.contains(content)
+cy.contains(selector, content)
+cy.contains(selector, content, options)
+```
 
-| | |
-|--- | --- |
-| **Returns** | the deepest DOM element containing the text  |
-| **Timeout** | `cy.contains` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) |
+## Parameters
 
-# [cy.contains( *text* )](#text-usage)
+**content**
 
-Get the deepest DOM element containing the text.
+Get the deepest DOM element containing the content. Content can be a:
 
-# [cy.contains( *number* )](#number-usage)
+- *string*
+- *number*
+- *regular expression*
 
-Get the deepest DOM element containing the number.
+**selector**
 
-# [cy.contains( *regexp* )](#regular-expression-usage)
+Specify a selector to filter DOM elements containing the text. Cypress will *ignore* it's [default preference order](#notes) for the specified selector. Using a selector allows you to return more *shallow* elements in the tree which contain the specific text.
 
-Get the deepest DOM element containing the text matching the regular expression.
-
-# [cy.contains( *selector*, *text* )](#selector-and-text-usage)
-
-Specify a selector to filter DOM elements containing the text. Cypress will **ignore** it's default preference for the specified selector. Using a selector allows you to return more *shallow* elements in the tree which contain the specific text.
-
-# Options
+**options**
 
 Pass in an options object to change the default behavior of `cy.contains`.
 
-**cy.contains( *text*, *options* )**
-**cy.contains( *selector*, *text*, *options* )**
-
 Option | Default | Notes
 --- | --- | ---
 `log` | `true` | whether to display command in command log
-`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry finding an element
+`timeout` | [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) | Total time to retry finding an element containing the content
 
-# Text Usage
+## Yields
 
-## Find the first element containing some text
+`cy.contains()` yields the *first*, *deepest* DOM element containing the text.
+
+## Timeout
+
+`cy.contains()` will try to find the content within the DOM for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts)
+
+# Examples
+
+## String Content
+
+**Find the first element containing some text**
 
 ```html
 <ul>
@@ -59,11 +60,13 @@ Option | Default | Notes
 ```
 
 ```javascript
-// returns <li>apples</li>
-cy.contains("apples")
+// yields <li>apples</li>
+cy.contains('apples')
 ```
 
-## Find the input[type='submit'] by value
+**Find the input[type='submit'] by value**
+
+Get the form element and search in its descendants for the content "submit the form!"
 
 ```html
 <div id="main">
@@ -82,14 +85,13 @@ cy.contains("apples")
 ```
 
 ```javascript
-// get the form element
-// search inside its descendants for the content 'submit the form!'
-// find the input[type='submit'] element
-// click it
-cy.get("form").contains("submit the form!").click()
+// yields input[type='submit'] element then clicks it
+cy.get('form').contains('submit the form!').click()
 ```
 
-## Favor of `button` over other deeper elements
+**Favor of `button` over other deeper elements**
+
+Even though the `<span>` is the deepest element that contains "Search", Cypress will yield `button` elements over spans.
 
 ```html
 <form>
@@ -101,21 +103,16 @@ cy.get("form").contains("submit the form!").click()
 ```
 
 ```javascript
-// even though the <span> is the deepest element that contains: "Search"
-// Cypress will automatically favor button elements higher in the chain
-
-// in this case the <button> is returned which is why we can now drill
-// into its children
-cy.contains("Search").children("i").should("have.class", "fa-search")
+// yields <button>
+cy.contains('Search').children('i').should('have.class', 'fa-search')
 ```
 
-## Favor of `a` over other deeper elements
+**Favor of `a` over other deeper elements**
+
+Even though the `<span>` is the deepest element that contains "Sign Out", Cypress will yield anchor elements over spans.
 
 ```html
 <nav>
-  <a href="/dashboard">
-    <span>Dashboard</span>
-  </a>
   <a href="/users">
     <span>Users</span>
   </a>
@@ -126,14 +123,15 @@ cy.contains("Search").children("i").should("have.class", "fa-search")
 ```
 
 ```javascript
-// even though the <span> is the deepest element that contains: "Sign Out"
-// Cypress will automatically favor anchor elements higher in the chain
-
-// in this case we can assert on the anchors properties
-cy.get("nav").contains("Sign Out").should("have.attr", "href", "/signout")
+// yields <a>
+cy.get('nav').contains('Sign Out').should('have.attr', 'href', '/signout')
 ```
 
-## Favor of `label` over other deeper elements
+**Favor of `label` over other deeper elements**
+
+Even though the `<span>` is the deepest element that contains "Age", Cypress will yield `label` elements over `span`.
+
+Additionally we don't need to look for content "Age:" omit as long as the element at least contains the text "Age", it will be yielded.
 
 ```html
 <form>
@@ -149,16 +147,11 @@ cy.get("nav").contains("Sign Out").should("have.attr", "href", "/signout")
 ```
 
 ```javascript
-// even though the <span> is the deepest element that contains: "Age"
-// Cypress will favor label elements higher in the chain
-
-// additionally we can omit the colon as long as the element
-// at least contains the text 'Age'
-
-cy.contains("Age").find("input").type("29")
+// yields label
+cy.contains('Age').find('input').type('29')
 ```
 
-## Only the *first* matched element will be returned
+**Only the *first* matched element will be returned**
 
 ```html
 <ul id="header">
@@ -167,28 +160,31 @@ cy.contains("Age").find("input").type("29")
 <div id="main">
   <span>These users have 10 connections with Jane Lane</span>
   <ul>
-    <li>User 1</li>
-    <li>User 2</li>
-    <li>User 3</li>
+    <li>Jamal</li>
+    <li>Patricia</li>
   </ul>
 </div>
 ```
 
+The below example will return the `<li>` in the `#header` since that is the *first* element that contains the text "Jane Lane".
+
 ```javascript
-// this will return the <li> in the #header since that is the first
-// element that contains the text "Jane Lane"
-cy.contains("Jane Lane")
-
-// if you want to select the <span> inside of #main instead
-// you need to scope the contains first
-
-//now the <span> is returned
-cy.get("#main").contains("Jane Lane")
+// yields #header li
+cy.contains('Jane Lane')
 ```
 
-# Number Usage
+If you wanted to select the `<span>` instead, you could narrow the elements yielded before the `.contains()`.
 
-## Find the first element containing some number
+```javascript
+// yields <span>
+cy.get('#main').contains('Jane Lane')
+```
+
+## Number Content
+
+**Find the first element containing some number**
+
+Even though the `<span>` is the deepest element that contains a "4", Cypress will automatically yield `button` elements higher in the chain
 
 ```html
 <button class="btn btn-primary" type="button">
@@ -197,16 +193,13 @@ cy.get("#main").contains("Jane Lane")
 ```
 
 ```javascript
-// even though the <span> is the deepest element that contains: 4
-// Cypress will automatically favor button elements higher in the chain
-
-// in this case the <button> is returned
+// yields <button>
 cy.contains(4)
 ```
 
-# Regular Expression Usage
+## Regular Expression Content
 
-## Find the first element with text matching the regular expression
+**Find the first element with text matching the regular expression**
 
 ```html
 <ul>
@@ -217,13 +210,19 @@ cy.contains(4)
 ```
 
 ```javascript
-// <li>bananas</li> is returned
+// yields <li>bananas</li>
 cy.contains(/^b\w+/)
 ```
 
-# Selector and Text Usage
+## Selector
 
-## Specify a selector to return a specific element
+**Specify a selector to return a specific element**
+
+Technically the `<html>`, `<body>`, `<ul>`, and first `<li>` in the example below all contain "apples".
+
+Normally Cypress would return the first `<li>` since that is the *deepest* element that contains: "apples"
+
+To override the element that is yielded, we can pass `ul` as the selector.
 
 ```html
 <html>
@@ -238,95 +237,92 @@ cy.contains(/^b\w+/)
 ```
 
 ```javascript
-// technically the <html>, <body>, <ul>, and first <li> all contain "apples"
-
-// normally Cypress would return the first <li> since that is the deepest
-// element that contains: "apples"
-
-// to override this behavior, pass a 'ul' selector
-// this returns the ul element since it also contains the text
-
-// returns <ul>...</ul>
-cy.contains("ul", "apples")
+// yields <ul>...</ul>
+cy.contains('ul', 'apples')
 ```
 
 # Notes
 
-## Dual command can be either parent or child
+**Element preference order**
+
+- `input[type='submit']`
+- `button`
+- `a`
+- `label`
+
+**Dual command can be either parent or child**
 
 `cy.contains` is a dual command.  This means it can act as both a `parent` and a `child` command.  Read more about [issuing commands](https://on.cypress.io/guides/issuing-commands) if this is unfamiliar.
 
 Because it is a dual command it can either *begin* a chain of commands or work off of an *existing* subject.
 
-**Start a chain of commands**
+***Start a chain of commands***
+
+Search for the content within the `document`.
 
 ```javascript
-// search from the root scope (default: document)
-cy.contains("some content")
+cy.contains('some content')
 ```
 
-**Find content within an existing scope**
+***Find content within an existing scope***
+
+Search within an existing subject for the content. `.contains()` will be scoped to the `<aside>` element and will only search it's DOM descendants for the content.
 
 ```javascript
-// search within an existing subject for the content
-// contains is now scoped to the <aside> element and will
-// only search its DOM descendants for the content
-cy.get("#main").find("aside").contains("Add a user")
+cy.get('#main').find('aside').contains('Add a user')
 ```
 
-**Be wary of chaining multiple contains**
+***Be wary of chaining multiple contains***
+
+Let's imagine a scenario where you click button to delete a user and a dialog appears asking you to confirm this deletion.
+
+The following will not work:
 
 ```javascript
-// let's imagine a scenario where you click a user's delete button
-// and a dialog appears asking you to confirm this deletion.
 
-// the following will not work:
 cy
-  .contains("Delete User").click()
-
-  // because this is chained off of the existing button subject
-  // Cypress will look inside of the existing button subject
-  // for the new content
-
-  // in other words Cypress will look inside of the element
-  // containing "Delete User" for the content: "Yes I'm sure!"
-  .contains("Yes, I'm sure!").click()
-
+  .contains('Delete User').click()
+  .contains('Yes, Delete!').click()
 ```
 
-**End previous chains to get back to the root scope**
+Because the second `.contains()` is chained off of the existing button subject, Cypress will look inside of the existing button subject for the new content.
+
+In other words, Cypress will look inside of the button containing "Delete User" for the content: "Yes, Delete!"
+
+***End previous chains to get back to the root scope***
+
+If you explicitly [`.end()`](https://on.cypress.io/api/end) the previous chain, Cypress within the `document` for the content.
 
 ```javascript
 cy
-  // explicitly .end() the previous chain
-  .contains("Delete User").click().end()
-
-  // Cypress will now search the root scope
-  // for this content (default: document)
-  .contains("Yes, I'm sure!").click()
+  .contains('Delete User').click().end()
+  .contains('Yes, Delete!').click()
 ```
 
-```javascript
-// alternatively just call cy again which
-// automatically creates a new chain from the root scope
-cy.contains("Delete User").click()
-cy.contains("Yes I'm sure!").click()
-```
+Alternatively, you could call `cy` again which automatically creates a new chain from the `document`.
+
+```javascript
+cy.contains('Delete User').click()
+cy.contains('Yes, Delete!').click()
+```
+
+You could also chain the second contains off of a parent command (such as [`.get()`](https://on.cypress.io/api/get). This automatically changes the subject to `#dialog` which contains the content we're looking for.
 
 ```javascript
-// you can also do this
 cy
-  .contains("Delete User").click()
-
-  // by using the parent command .get() we automatically
-  // abort previous chains and change the scope to #dialog
-  // which contains the content we're looking for
-  .get("#dialog").contains("Yes I'm sure!").click()
+  .contains('Delete User').click()
+  .get('#dialog').contains('Yes, Delete!').click()
 ```
 
 # Command Log
 
-## Element contains text "New User"
+**Element contains text "New User"**
+
+```javascript
+cy.get('h1').contains('New User')
+```
+
+The commands above will display in the command log as:
 
 <img width="536" alt="screen shot 2015-11-27 at 1 43 22 pm" src="https://cloud.githubusercontent.com/assets/1271364/11446973/009ac32c-950d-11e5-9eaa-09f8b8ddf086.png">
 
@@ -334,7 +330,7 @@ When clicking on the `contains` command within the command log, the console outp
 
 <img width="477" alt="screen shot 2015-11-27 at 1 43 50 pm" src="https://cloud.githubusercontent.com/assets/1271364/11446977/04b31be4-950d-11e5-811e-4fd83d364d00.png">
 
-# Related
+# See also
 
 - [get](https://on.cypress.io/api/get)
 - [within](https://on.cypress.io/api/within)