Enhance README and API reference

API.md

@@ -10,6 +10,10 @@
     -   [triggerEvent](#triggerevent)
     -   [triggerKeyEvent](#triggerkeyevent)
     -   [fillIn](#fillin)
+-   [DOM Query Helpers](#dom-query-helpers)
+    -   [find](#find)
+    -   [findAll](#findall)
+    -   [getRootElement](#getrootelement)
 -   [Routing Helpers](#routing-helpers)
     -   [visit](#visit)
     -   [currentRouteName](#currentroutename)
@@ -40,9 +44,6 @@
     -   [setupApplicationContext](#setupapplicationcontext)
     -   [teardownApplicationContext](#teardownapplicationcontext)
     -   [validateErrorHandler](#validateerrorhandler)
--   [getRootElement](#getrootelement)
--   [find](#find)
--   [findAll](#findall)
 
 ## DOM Interaction Helpers
 
@@ -200,6 +201,39 @@ events on the specified target.
 
 Returns **[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)<void>** resolves when the application is settled
 
+## DOM Query Helpers
+
+
+
+
+### find
+
+Find the first element matched by the given selector. Equivalent to calling
+`querySelector()` on the test root element.
+
+**Parameters**
+
+-   `selector` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the selector to search for
+
+Returns **[Element](https://developer.mozilla.org/docs/Web/API/Element)** matched element or null
+
+### findAll
+
+Find all elements matched by the given selector. Equivalent to calling
+`querySelectorAll()` on the test root element.
+
+**Parameters**
+
+-   `selector` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the selector to search for
+
+Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** array of matched elements
+
+### getRootElement
+
+Get the root element of the application under test (usually `#ember-testing`)
+
+Returns **[Element](https://developer.mozilla.org/docs/Web/API/Element)** the root element
+
 ## Routing Helpers
 
 
@@ -544,31 +578,3 @@ test('Ember.onerror is functioning properly', function(assert) {
 ```
 
 Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** object with `isValid` and `message`
-
-## getRootElement
-
-Get the root element of the application under test (usually `#ember-testing`)
-
-Returns **[Element](https://developer.mozilla.org/docs/Web/API/Element)** the root element
-
-## find
-
-Find the first element matched by the given selector. Equivalent to calling
-`querySelector()` on the test root element.
-
-**Parameters**
-
--   `selector` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the selector to search for
-
-Returns **[Element](https://developer.mozilla.org/docs/Web/API/Element)** matched element or null
-
-## findAll
-
-Find all elements matched by the given selector. Equivalent to calling
-`querySelectorAll()` on the test root element.
-
-**Parameters**
-
--   `selector` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** the selector to search for
-
-Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)** array of matched elements

README.md

@@ -1,49 +1,68 @@
-# @ember/test-helpers [![Build Status](https://secure.travis-ci.org/emberjs/ember-test-helpers.svg?branch=master)](http://travis-ci.org/emberjs/ember-test-helpers)
+@ember/test-helpers
+==============================================================================
 
-A test-framework-agnostic set of helpers for testing Ember.js applications.
+[![Build Status](https://secure.travis-ci.org/emberjs/ember-test-helpers.svg?branch=master)](http://travis-ci.org/emberjs/ember-test-helpers)
 
-## Usage
+A test-framework-agnostic set of helpers for testing Ember.js applications
 
-The exports of this library are intended to be utility functions that can be used to bring the
-standard Ember testing experience to any testing framework.
+Installation
+------------------------------------------------------------------------------
 
-This library is best used by way of a test-framework-specific
-wrapper, such as [ember-qunit](https://github.com/emberjs/ember-qunit) or
-[ember-mocha](https://github.com/emberjs/ember-mocha).
+If you are writing a regular Ember app or addon there is not much for you to
+do as [ember-qunit](https://github.com/emberjs/ember-qunit) (and
+[ember-mocha](https://github.com/emberjs/ember-mocha)) already include this
+package as a dependency. You only need to make sure that you are using a
+recent enough version of either one of these packages.
 
-**Full documentation can be found in [API.md](API.md).**
+If you are working on `ember-qunit` or `ember-mocha` themselves you can
+install this package like any other regular Ember addon. 
 
-## Collaborating
+
+Usage
+------------------------------------------------------------------------------
+
+This package exports several helper functions that can be used to improve
+the testing experience when developing Ember.js apps or addons.
+
+These helper functions include DOM interaction helpers (`click()`, `fillIn()`,
+...), routing and rendering helpers (`visit()`, `render()`, ...) and some
+other things that make it easy to write good tests.
+
+**The full documentation can be found in the [API reference](API.md).**
+
+
+Contributing
+------------------------------------------------------------------------------
 
 ### Installation
 
-* `git clone <repository-url>` this repository
+* `git clone <repository-url>`
 * `cd ember-test-helpers`
 * `yarn install`
 
-### Running
-
-* `ember serve`
-* Visit your app at [http://localhost:4200](http://localhost:4200).
-
-### Running Tests
+### Running tests
 
 * `yarn test` (Runs `ember try:each` to test your addon against multiple Ember versions)
 * `ember test`
 * `ember test --server`
 
-### Building
+### Running the dummy application
 
-* `ember build`
+* `ember serve`
+* Visit the dummy application at [http://localhost:4200](http://localhost:4200).
 
 For more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/).
 
-## Attribution
+
+Attribution
+------------------------------------------------------------------------------
 
 Much of `ember-test-helpers` was extracted from the original `ember-qunit`,
 which was written by Stefan Penner, Robert Jackson, and Ryan Florence.
 
-## Copyright and License
+
+Copyright and License
+------------------------------------------------------------------------------
 
 Copyright 2015 [Switchfly](https://github.com/switchfly) and contributors.
 

documentation.yml

@@ -9,6 +9,12 @@ toc:
       - triggerKeyEvent
       - fillIn
 
+  - name: DOM Query Helpers
+    children:
+      - find
+      - findAll
+      - getRootElement
+
   - name: Routing Helpers
     children:
       - visit