task docs improvements (#402)

Author: casperdcl

README.md

@@ -10,7 +10,7 @@ The Iterative Provider makes it easy to:
 - Rapidly move local machine learning experiments to a cloud infrastructure
 - Take advantage of training models on spot instances without losing any progress
 - Unify configuration of various cloud compute providers
-- Automatically destroy unused cloud resources (never forget to turn your GPU off again)
+- Automatically destroy unused cloud resources (compute instances are terminated on job completion/failure, and storage is removed when results are downloaded)
 
 The Iterative Provider can provision resources with the following cloud providers and orchestrators:
 

docs/guides/getting-started.md

@@ -38,7 +38,7 @@ resource "iterative_task" "task" {
 
 See [the reference](https://registry.terraform.io/providers/iterative/iterative/latest/docs/resources/task) for a full list of options -- including more information on [`machine` types](https://registry.terraform.io/providers/iterative/iterative/latest/docs/resources/task#machine-type).
 
--> **Note:** The `script` argument can take any string, including a [heredoc](https://www.terraform.io/docs/language/expressions/strings.html#heredoc-strings) or the contents of a file returned by the [`file`](https://www.terraform.io/docs/language/functions/file.html) function.
+-> **Note:** The `script` argument must begin with a valid [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>), and can take the form of a [heredoc string](https://www.terraform.io/docs/language/expressions/strings.html#heredoc-strings) or [a `file()` function](https://www.terraform.io/docs/language/functions/file.html) function (e.g. `file("task_run.sh")`).
 
 The project layout should look similar to this:
 

docs/index.md

@@ -38,19 +38,25 @@ $ terraform apply
 - `AWS_SECRET_ACCESS_KEY` - Secret access key.
 - `AWS_SESSION_TOKEN` - (Optional) Session token.
 
+See the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) for more information.
+
 ### Microsoft Azure
 
 - `AZURE_CLIENT_ID` - Client identifier.
 - `AZURE_CLIENT_SECRET` - Client secret.
 - `AZURE_SUBSCRIPTION_ID` - Subscription identifier.
 - `AZURE_TENANT_ID` - Tenant identifier.
 
+See the [Azure documentation](https://docs.microsoft.com/en-us/python/api/azure-identity/azure.identity.environmentcredential) for more information.
+
 ### Google Cloud Platform
 
 - `GOOGLE_APPLICATION_CREDENTIALS` - Path to a service account JSON key file.
 
 -> **Note:** you can also use `GOOGLE_APPLICATION_CREDENTIALS_DATA` with the **contents** of the service account JSON key file.
 
+See the [GCP documentation](https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account) for more information.
+
 ### Kubernetes
 
 - `KUBECONFIG` - Path to a [`kubeconfig` file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#the-kubeconfig-environment-variable).

docs/resources/task.md

@@ -30,7 +30,7 @@ resource "iterative_task" "task" {
 ### Required
 
 - `cloud` - (Required) Cloud provider to run the task on; valid values are `aws`, `gcp`, `az` and `k8s`.
-- `script` - (Required) Script to run; must begin with a valid [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>).
+- `script` - (Required) Script to run (relative to `workdir.input`); must begin with a valid [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). Can use a string, including a [heredoc](https://www.terraform.io/docs/language/expressions/strings.html#heredoc-strings), or the contents of a file returned by the [`file`](https://www.terraform.io/docs/language/functions/file.html) function.
 
 ### Optional