edited user interface docs

docs/user_guide/user_interface/dashboard.rst

@@ -6,17 +6,21 @@
 Dashboard
 =============
 
-The Dashboard Client is designed to give you a summary of your ClarityNLP instance at a glance. On page load, you can see the latest:
+The Dashboard is designed to give you a summary of your ClarityNLP instance at a glance.
+The Dashboard shows you the following:
 
-* The amount and name of Documents you have uploaded
-* The name and verison of NLPQL you have created and saved via the `Query Builder`_
-* the name, date, runtime, cohort size, and validation of Results from jobs that have been run
+* The document types (and number of each type) stored in your Solr instance
+* The NLPQL queries you have created and saved via the `Query Builder`_
+* The name, date, runtime, cohort size, and validation status of your NLPQL jobs
 
 .. image:: ./images/claritynlp_dashboard_1.png
 
 --------
 
-In order to view all of your documents, results, or nlpql; simply click on the expand button to the top right of the corresponding box. This will expand the box to full screen and provide more information on the given field. To return to the default view, simply click on the collapse button located in the top right corner.
+To view all of your documents, results, or NLPQL queries, simply click on the expand
+button at the top right of the corresponding box.
+This action expands the box to full screen and provides more information on the given field.
+To return to the default view, click on the collapse button located at the top right corner.
 
 .. image:: ./images/claritynlp_dashboard_2.png
 .. image:: ./images/claritynlp_dashboard_3.png
@@ -25,8 +29,16 @@ In order to view all of your documents, results, or nlpql; simply click on the e
 Additional Features
 --------
 
-If you would like to quickly navigate to the results of one your recent jobs. You can click on the job row in the results table to go directly to that job's results in the `Results Viewer`_.
+If you would like to quickly navigate to the results of one your recent jobs,
+you can click on that job's row in the results table to go directly to the results
+in the `Results Viewer`_.
+
+Alternatively, if you would like to open the NLPQL file of a previously saved query,
+click on the respective row in the NLPQL table to open that query in the `Query Builder`_.
+
+You can run saved queries by pressing the play button (right-pointing arrowhead)
+in the same row as the query.
+
+You can delete a saved query by pressing the trash can icon next to the name of the query.
 
-Alternatively, if you would like to open the NLPQL of a previously saved query, you can click on the respective row in the NLPQL table to open that query in the `Query Builder`_.
 
-You can also run or delete NLPQL from the NLPQL table using the play button or trash can on the corresponding row of the query.

docs/user_guide/user_interface/query_builder.rst

@@ -6,43 +6,49 @@
 Query Builder
 =============
 
-The Query Builder is a tool to assist in the development of NLPQL.
+The Query Builder is a tool to assist in the development of NLPQL queries.
 
-When you first get to the page, it will prompt you with a name and version for your NLPQL.
+When you open the Query Builder, it will prompt you to enter a name and version number for your NLPQL query.
 
-NOTE: Your NLPQL MUST have a unique version if the name of the query has already been saved.
+NOTE: a previously-saved query cannot be overwritten. Each query must be saved with a unique version number.
 
 .. image:: ./images/claritynlp_builder_1.png
 
 After you have named and versioned your query, you can begin building your query.
 
 .. image:: ./images/claritynlp_builder_2.png
 
-To add a component to the query, simply click on the component you would like to add, fill out the fields that you need, and click the corresponding add button.
+To add a component to the query, simply click on the component you would like to add,
+fill out the fields that you need, and click the corresponding add button.
 
 .. image:: ./images/claritynlp_builder_3.png
 
 .. image:: ./images/claritynlp_builder_4.png
 
-After you finish building your query, you can click the save button just above the dropdowns to save your query indefinitely. You can also run the query by clicking the run button to the top right. 
+After you finish building your query, you can click the save button just above the
+dropdowns to save your query indefinitely. You can also run the query by clicking the
+run button at the top right. 
 
-This is where you can add a limit to your query if you want to.
+You can specify a limit to the number of documents processed by using an NLPQL ``limit`` statement.
+The form in the next image allows you to specify a limit:
 
 .. image:: ./images/claritynlp_builder_5.png
 
-If running the query was successful, you will be prompted with a JSON with some metadata about your query.
+If your NLPQL query passes the validity checks, you will be shown some metadata about your query:
 
 .. image:: ./images/claritynlp_builder_7.png
 
-NOTE: If at any point you want to scrap your query you can click the clear button at the bottom of the text area to start over.
+NOTE: If at any point you want to delete your query you can click the clear button at
+the bottom of the text area to start over.
 
 Loading a Query
 -------------
 
-If you navigated here from a link or the `Dashboard`_, your query will automatically load into the text area.
+If you navigated here from a link or from the `Dashboard`_, your query will automatically
+load into the text area.
 
 .. image:: ./images/claritynlp_builder_6.png
 
-You can edit this query by clicking the edit button below the text area. This will make the text area free form and you can edit it however you see fit. 
+You can edit this query by clicking the edit button below the text area.
 
-NOTE: We only recommend doing this if you have experience building NLPQL from scratch, to learn more about this check out the `NLPQL Reference`_.
+To learn more about NLPQL, please see the `NLPQL Reference`_.

docs/user_guide/user_interface/results_viewer.rst

@@ -3,68 +3,81 @@
 Results Viewer
 ==============
 
-The Results viewer is designed to give you a comprehensive look at all of the results that have come from a query you have run on your ClarityNLP instance.
+The Results viewer is designed to give you a comprehensive look at the results from a ClarityNLP run.
 
-The first screen will provide with the first 20 jobs that have been run. You can navigate the results by using the Next page and Previous button to the top right of the list. Each Job has many interactions associated with it. The columns available for each job is:
+The first screen provides a list of the 20 most recently-submitted jobs.
+You can navigate the results by using the "Next page" and "Previous" buttons at the top right of the list.
+Each job has many interactions associated with it, which are:
 
-- The name of the query that was run
-- The date the query was run
-- The current status of the job, *If not complete* this will appear as a link that will take you to the luigi link for that job
+- The name of the query
+- The query submission date
+- The current status of the job.
+  If the job is not finished, the job status appears as a hyperlink that takes
+  you to the Luigi task viewer for that job.
 - The cohort size for that particular query
-- The accuracy score associated with that query
+- The accuracy score from an evaluation of the results
 - Download links for the job that includes CSVs of:
     - Results
     - Cohort
     - Annotations
-- Actions that can be taken on the job, which includes:
+- Actions that can be taken for the job, which include:
     - Viewing the text representation of the query
     - Viewing the JSON representation of the query
     - Deleting the job
 
-NOTE: Deleting a job is permanent and cannot be undone.
+NOTE: Job deletion is permanent and cannot be undone.
 
 .. image:: ./images/claritynlp_viewer_1.png
 .. image:: ./images/claritynlp_viewer_5.png
 .. image:: ./images/claritynlp_viewer_4.png
 .. image:: ./images/claritynlp_viewer_12.png
 
-This list is also searchable based on the search criteria entered in the search field above.
+This list is also searchable via terms entered into the text box above the list:
 
 .. image:: ./images/claritynlp_viewer_13.png
 
-To delve deeper into a job, click on that job's row in the list. This will bring you to a screen where you can see the multiple patients that came back with results from the query. You can also see the number of events that were recognized for each of those patients.
+To delve deeper into the results for a job, click on that job's row in the list.
+This brings you to a screen where you can see individual results from the query.
+You can also see the number of events that were recognized for each result.
 
 .. image:: ./images/claritynlp_viewer_2.png
 
 If no results were found for a query, a blank screen will appear.
 
 .. image:: ./images/claritynlp_viewer_8.png
 
-To the top right of the page, you can cycle through the Explore view, Feature view, and Cohort view. The Feature view and Cohort view will appear as tables that you can scroll through. The Explore view is the default.
+At the top right of the page, you can cycle through the "Explore", "Feature", and "Cohort" views.
+The Feature and Cohort views appear as scrollable tables. The Explore view is the default.
 
 .. image:: ./images/claritynlp_viewer_3.png
 .. image:: ./images/claritynlp_viewer_11.png
 
-If you want to view the results for a patient, click that patient's row in the list. This will bring you to a screen where you can view each result individually.
+If you want to view the results for a patient, click that patient's row in the list.
+This will bring you to a screen where you can see highlighted results.
 
 .. image:: ./images/claritynlp_viewer_10.png
 
-The Next Page and Previous buttons to the top right will cycle you through the various patients for that job. 
+The "Next Page" and "Previous" buttons to the top right will cycle you through the various patients for that job. 
 
-To the left of the page, you can view NLPQL features that have results. Clicking one of these features, will filter the results that you see to the right of the page. All results are populated by default.
+At the left side of the page is a list of the NLPQL features for which results were found.
+Clicking one of these features will show the results for that feature only.
+All results are displayed by default.
 
 .. image:: ./images/claritynlp_viewer_9.png
 
-Each result has a feature, an outcome, and a sentence associated with it. The feature is the feature from the query that provided the result. The outcome is a small synopsis of what the algorithm found based on a patient's document. The sentence is the sentence from the report that the outcome was found. 
+Each result box shows the name of the relevant NLPQL feature, the definition
+of that feature immediately below it, and an extract from a source document.
+The extract highlights relevant terms and values associated with the feature.
+
+In the upper right corner of each result box is a set of buttons that can be
+used to evaluate ClarityNLP's results. You can:
 
-Each result also has a number of actions that you can take to help improve the functionality of the algorithms used to provide results. You can:
-
-- Click the check if the result was helpful
-- Click the X if the result was not helpful
-- Click the notepad to leave a comment about the result
+- Click the checkmark if the result is correct
+- Click the X if the result is incorrect
+- Click the notepad to enter a comment about the result
 
 .. image:: ./images/claritynlp_viewer_6.png
 
-To see the full report where a result was found, you can click on the sentence.
+You can click on the sentence to view the complete source document:
 
 .. image:: ./images/claritynlp_viewer_7.png