Adds revisions and clarification[#134606323]

Author: sleslie

using-tasks.html.md.erb

@@ -5,70 +5,66 @@ owner: CAPI
 
 <strong><%= modified_date %></strong>
 
-This topic describes how to run tasks in Cloud Foundry. 
-
-Tasks are processes that are executed one time in the context of a given application. A task is only run at most once.
+This topic describes how to run tasks in Cloud Foundry. A task is an application or script whose code is included as part of a deployed application, but runs independently in its own container.
 
 ## <a id='about-tasks'></a> About Tasks
 
-In contrast to a long running process (LRP), tasks run for a finite amout of time, then stop. Tasks run in their own containers and are designed to use minimal resources. After the task runs, Cloud Foundry destroys the container running the task.
+In contrast to a long running process (LRP), tasks run for a finite amout of time, then stop. Tasks run in their own containers and are designed to use minimal resources. After a task runs, Cloud Foundry destroys the container running the task.
 
 As a single-use object, a task can be checked for its state and for a success or failure message.
 
 ### <a id="use-cases"></a> Use Cases for Tasks
 
-Tasks are used to perform one-off jobs. For example, you can use a task to:
+Tasks are used to perform one-off jobs, which can include:
 
-* Migrate a database
-* Send an email
-* Run a batch job
-* Run a data processing script
-* Process images
-* Optimize a search index
-* Upload data
-* Backup data
-* Download content
+* Migrating a database
+* Sending an email
+* Running a batch job
+* Running a data processing script
+* Processing images
+* Optimizing a search index
+* Uploading data
+* Backing-up data
+* Downloading content
 
 ###<a id="task-proceses"></a> How Tasks Are Run
 
 The life-cycle of a task is:
 
-1. A user initiates a task in Cloud Foundry. A user can initiate a task in CF by using one of the following mechanisms:
-   *  `cf run-task APPNAME TASK` command. See 			
+1. A user initiates a task in Cloud Foundry using one of the following mechanisms:
+   *  `cf run-task APPNAME "TASK"` command. See [Running Tasks](#run-tasks)			
    * Cloud Controller v3 API call. See the [Tasks](http://v3-apidocs.cloudfoundry.org/version/3.0.0/index.html#tasks) API reference page.
    * Cloud Foundry Java Client. See [Cloud Foundry Java Client Library](../buildpacks/java/java-client.html) and [Cloud Foundry Java Client](https://github.com/cloudfoundry/cf-java-client).
 
-1. Cloud Foundry creates container specifically for the task.
-1. Cloud Foundry runs the task on the container using the value provided to the `cf run-task` command
-1. Cloud Foundry destroys container
+1. Cloud Foundry creates a container specifically for the task.
+1. Cloud Foundry runs the task on the container using the value passed to the `cf run-task` command.
+1. Cloud Foundry destroys container.
+
+When creating the container, Cloud Foundry uses the disk size and memory allocation specified for the parent application. The new container respects app, space, and organization-level memory quotas. The container also inherits environment variables, service bindings and security groups bound to the application. Tasks have a memory limit and a disk limit (global cloud foundry defaults for app memory in your bosh manifest or in ERT Application Developer Controls).
 
-* A task includes the command to start the process, disk size, and memory allocation
-* A task inherits environment variables, service bindings and security groups bound to the application
-* Tasks respect app, space, and organization level memory quotas
-* Tasks have a memory limit and a disk limit (global cloud foundry defaults for app memory in your bosh manifest or in ERT Application Developer Controls) 
-* Tasks are always executed asynchronously
+Tasks are always executed asynchronously, meaning that they run independently from the parent application or other tasks run on the same application.
 
-<p class="note"><strong>Note</strong>: You cannot SSH into a running task.</p>
+<p class="note"><strong>Note</strong>: You cannot SSH into the container running a task.</p>
 
 ### Task Logging and Execution History
 
-* Task execution history is retained for one month. 
-* A syslog drain attached to an app will receive task log output
-* Stdout/stderr from the task will be available on the app’s firehose logs
+Any data or messages the task outputs to STDOUT or STDERR is be available on the app’s firehose logs. A syslog drain attached to the app receives the task log output.
 
-## <a id='manage-tasks'></a> Managing Tasks
+The task execution history is retained for one month. 
+
+## <a id='manage-tasks'></a> Manage Tasks
 
 * Admins can use the Cloud Controller v3 API to view all the tasks that are running in an org or space. See http://v3-apidocs.cloudfoundry.org/version/3.0.0/index.html#list-tasks
 
 * Admins can set memory usage on a global level (link)
 
-## <a id='run-tasks'></a> Running Tasks
+## <a id='run-tasks'></a> Run a Task on an Application
 
 You can use the cf CLI to run a task in the context of an application. 
 
 <p class="note"><strong>Note</strong>: To run tasks with the cf CLI, you must install the cf CLI v6.23 (?) or later. See the <a href="../cf-cli/install-go-cli.html">Installing the Cloud Foundry Command Line Interface</a> topic for information about downloading, installing, and uninstalling the cf CLI.</p>
 
-To run a task on an application, first push your application. Then use the `cf run-task APPNAME TASK` command on your deployed application. For example:
+To run a task on an application, first push your application. Then, use the `cf run-task APP-NAME TASK` command on your deployed application. For example:
 
 <pre class="terminal">
 $ cf run-task my-app "bin/rails db:migrate"
@@ -77,11 +73,24 @@ OK
 Task 1 has been submitted successfully for execution.
 </pre>
 
-To re-run a task, you must create it as a new task.
+To re-run a task, you must run it as a new task using the above command.
+
+## <a id='list-tasks'></a> List Tasks Running on an Application
+
+To list the tasks for a given application, run the `cf tasks APP-NAME`. For example:
+
+<pre class="terminal">
+$ cf tasks my-app
+Getting tasks for app sl-rails-blog in org cf-docs-sandbox / space development as [email protected]...
+OK
 
-## <a id='list-tasks'></a> Listing Tasks
+id   name       state       start time                      command
+3    ec964e1a   SUCCEEDED   Fri, 09 Dec 2016 23:14:58 UTC   ./tasks/hello_world.sh
+2    b84302eb   SUCCEEDED   Fri, 09 Dec 2016 23:09:11 UTC   ./tasks/hello_world.sh
+1    491c8a57   SUCCEEDED   Fri, 09 Dec 2016 23:08:44 UTC   ./tasks/hello_world.sh
+</pre>
 
-Tasks have the following states:
+Each task has one of the following states:
 
 <table class="nice" border="1">
     <tr>
@@ -102,41 +111,10 @@ Tasks have the following states:
 	</tr>
 </table>
 
-## <a id='cancel-task'></a>
-
-* A task is cancellable
-
-
-To support running and managing tasks, the cf CLI supports the following commands:
-
-
-
-* <strong>Comment</strong> I think it would be nice to include more how tasks are run. Is there a queue? Is the task run in a separate container?
-* provide "architectural" information about how tasks work. For example, are they run in a separate container.
-* different container, same code
-
-For example, if you run cf run-task spring-music "echo blah", CF submits the task for execution and displays:
-
-<code>
-Creating task for app spring-music in org sleslie_pivotal / space development as [email protected]...
-OK
-
-Task 0 has been submitted successfully for execution.
-</code>
-
-To view the tasks running on an application:
-
-cf tasks spring-music
-
-id   name       state       start time                      command
-0    e4d3c654   SUCCEEDED   Tue, 15 Nov 2016 19:25:55 UTC   echo blah
-
-
-
-Cloud Foundry
-
+## <a id='cancel-task'></a> Cancel a Task
 
+After running a task, you may be able to cancel it before it finishes. To cancel a running task, use the `cf terminate-task APP-NAME TASK-ID` command.
 
 ## Sample Application
 
-The <strong>github_link_to_example</strong> application demonstrates ...
+<strong>Would be nice to have an example</strong>