copyediting (#292)

* tabulate generic images

- part of #267 & #158

* misc copyediting

* Restyle copyediting (#293)

* more consistency

particularly line wrapping

* minor table note

* docs: terraform fmt

* Apply suggestions from code review

Co-authored-by: Casper da Costa-Luis <casper.dcl@physics.org>

Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com>
Co-authored-by: Helio Machado <0x2b3bfa0+git@googlemail.com>

Author: 3 people

docs/guides/getting-started.md

@@ -10,14 +10,14 @@ Begin by [installing Terraform 1.0 or greater](https://learn.hashicorp.com/tutor
 
 In the project root directory:
 
-1. Create a directory named `shared` to store input data and output artifacts.
+1. Create a directory named `shared` to store input data and output artefacts.
 2. Create a file named `main.tf` with the following contents:
 
 ```hcl
 terraform {
   required_providers {
     iterative = {
-      source  = "iterative/iterative"
+      source = "iterative/iterative"
     }
   }
 }
@@ -29,23 +29,22 @@ resource "iterative_task" "example" {
   cloud = "aws" # or any of: gcp, az, k8s
 
   directory = "${path.root}/shared"
-
-  script = <<-END
+  script    = <<-END
     #!/bin/bash
     echo "Hello World!" > greeting.txt
   END
 }
 ```
 
--> **Note:** The `script` argument can take anny 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 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.
 
 The project layout should look similar to this:
 
 ```
 project/
-├─ shared/
-│ └─ ···
-└─ main.tf
+├── main.tf
+└── shared/
+    └── ...
 ```
 
 ## Initializing Terraform
@@ -91,14 +90,14 @@ This command will:
 ## Deleting Tasks
 
 ```console
-terraform destroy
+$ terraform destroy
 ```
 
 This command will:
 
 1. Download the specified shared `directory` from the cloud.
-2. Delete all the created cloud resources.
+2. Delete all the cloud resources created by `terraform apply`.
 
 ## Viewing Task Results
 
-After running `terraform destroy`, the `shared/` directory should contain a file named `greeting.txt` with the text `Hello, World!`
+After running `terraform destroy`, the `shared` directory should contain a file named `greeting.txt` with the text `Hello, World!`

docs/index.md

@@ -1,15 +1,14 @@
 # Iterative Provider
 
-Use the Iterative Provider to launch resource-intensive tasks in popular cloud
-providers with a single Terraform file.
+Use the Iterative Provider to launch resource-intensive tasks in popular cloud providers with a single Terraform file.
 
 ## Example Usage
 
 ```hcl
 terraform {
   required_providers {
     iterative = {
-      source  = "iterative/iterative"
+      source = "iterative/iterative"
     }
   }
 }
@@ -27,12 +26,11 @@ resource "iterative_task" "task" {
 }
 ```
 
--> **Note:** See the [Getting Started](https://registry.terraform.io/providers/iterative/iterative/latest/docs/guides/getting-started) for more information.
+-> **Note:** See [Getting Started](https://registry.terraform.io/providers/iterative/iterative/latest/docs/guides/getting-started) for more information.
 
 ## Authentication
 
-[Environment variables](https://registry.terraform.io/providers/iterative/iterative/latest/docs#authentication) are the only supported authentication method. They should
-be present when running any of the `terraform` commands.
+Environment variables are the only supported authentication method. They should be present when running any of the `terraform` commands.
 
 ### Example
 
@@ -51,8 +49,7 @@ $ terraform apply
 
 - `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.
+-> **Note:** you can also use `GOOGLE_APPLICATION_CREDENTIALS_DATA` with the **contents** of the service account JSON key file.
 
 ### Microsoft Azure
 

docs/resources/task.md

@@ -2,9 +2,9 @@
 
 This resource will:
 
-1. Create cloud resources (storage, machines) for the task
-2. Upload the given `directory` to the cloud storage, if specified
-3. Run the given `script` upon completion or `timeout` in the cloud
+1. Create cloud resources (machines and storage) for the task.
+2. Upload the given `directory` to the cloud storage, if specified.
+3. Run the given `script` until completion or `timeout` in the cloud machine.
 
 ## Example Usage
 
@@ -13,10 +13,9 @@ resource "iterative_task" "task" {
   name  = "example"
   cloud = "aws"
 
-  environment = {GREETING = "Hello, world!"}
+  environment = { GREETING = "Hello, world!" }
   directory   = "${path.root}/shared"
-
-  script = <<-END
+  script      = <<-END
     #!/bin/bash
     echo "$GREETING" | tee $(uuidgen)
   END
@@ -60,31 +59,23 @@ In addition to all arguments above, the following attributes are exported:
 
 ### Generic
 
-The Iterative Provider offers some common machine types which are roughly the same
-for all supported clouds.
-
-#### No GPU
-
-- `m` - Medium, with (at least), 8 CPU cores and 16 GB of RAM.
-- `l` - Large, with (at least) 32 CPU cores and 64 GB of RAM.
-- `xl` - Extra large, with (at least) 64 CPU cores and 128 GB of RAM.
-
-#### NVIDIA Tesla K80 GPU
-
-- `m+k80` - Medium, with (at least) 4 CPU cores, 53 GB of RAM and 1 GPU device.
-- `l+k80` - Large, with (at least) 12 CPU cores, 112 GB of RAM and 2 GPU devices.
-- `xl+k80` - Extra large, with (at least) 24 CPU cores, 212 GB of RAM and 4 GPU devices.
-
-#### NVIDIA Tesla V100 GPU
+The Iterative Provider offers some common machine types (medium, large, and extra large) which are roughly the same for all supported clouds.
 
-- `m+v100` - Medium, with (at least) 4 CPU cores, 61 GB of RAM and 1 GPU device.
-- `l+v100` - Large, with (at least) 12 CPU cores, 224 GB of RAM and 2 GPU devices.
-- `xl+v100` - Extra large, with (at least) 24 CPU cores, 448 GB of RAM and 4 GPU devices.
+| Type      | Minimum CPU cores | Minimum RAM | GPU                 |
+| :-------- | ----------------: | ----------: | :------------------ |
+| `m`       |                 8 |       16 GB | -                   |
+| `l`       |                32 |       64 GB | -                   |
+| `xl`      |                64 |      128 GB | -                   |
+| `m+k80`   |                 4 |       53 GB | 1 NVIDIA Tesla K80  |
+| `l+k80`   |                12 |      112 GB | 2 NVIDIA Tesla K80  |
+| `xl+k80`  |                24 |      212 GB | 4 NVIDIA Tesla K80  |
+| `m+v100`  |                 4 |       61 GB | 1 NVIDIA Tesla V100 |
+| `l+v100`  |                12 |      224 GB | 2 NVIDIA Tesla V100 |
+| `xl+v100` |                24 |      448 GB | 4 NVIDIA Tesla V100 |
 
 ### Cloud-specific
 
-In addition to generic types, it's possible to specify any machine type
-supported by the underlying cloud provider.
+In addition to generic types, it's possible to specify any machine type supported by the underlying cloud provider.
 
 #### Amazon Web Services
 
@@ -112,15 +103,13 @@ supported by the underlying cloud provider.
 
 ### Generic
 
-The Iterative Provider offers some common machine images which are roughly the same
-for all supported clouds.
+The Iterative Provider offers some common machine images which are roughly the same for all supported clouds.
 
-- `ubuntu` - Official Ubuntu LTS image, currently 20.04.
+- `ubuntu` - Official [Ubuntu LTS](https://wiki.ubuntu.com/LTS) image (currently 20.04).
 
 ### Cloud-specific
 
-In addition to generic images, it's possible to specify any machine image
-supported by the underlying cloud provider.
+In addition to generic images, it's possible to specify any machine image supported by the underlying cloud provider.
 
 #### Amazon Web Services
 
@@ -169,8 +158,7 @@ See https://docs.microsoft.com/en-us/azure/virtual-machines/linux/cli-ps-findima
 
 ### Generic
 
-The Iterative Provider offers some common cloud regions which are roughly the same
-for all supported clouds.
+The Iterative Provider offers some common cloud regions which are roughly the same for all supported clouds.
 
 - `us-east` - United States of America, East.
 - `us-west` - United States of America, West.
@@ -179,8 +167,7 @@ for all supported clouds.
 
 ### Cloud-specific
 
-In addition to generic regions, it's possible to specify any cloud region
-supported by the underlying cloud provider.
+In addition to generic regions, it's possible to specify any cloud region supported by the underlying cloud provider.
 
 #### Amazon Web Services
 
@@ -210,6 +197,6 @@ Setting the `region` attribute results in undefined behaviour.
 
 Unlike public cloud providers, Kubernetes does not offer any portable way of persisting and sharing storage between pods. When specified, the `directory` attribute will create a `PersistentVolumeClaim` of the default `StorageClass`, with the same lifecycle as the task and the specified `disk_size`.
 
-~> **Warning:** Access mode will be `ReadWriteOnce` for `parallelism` equal to 1 or `ReadWriteMany` otherwise.
+~> **Warning:** Access mode will be `ReadWriteOnce` if `parallelism=1` or `ReadWriteMany` otherwise.
 
 -> **Note:** Rancher's [Local Path Provisioner](https://github.com/rancher/local-path-provisioner) might be the easiest way of deploying a quick `ReadWriteOnce` dynamically allocated storage solution for testing: just run `kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yaml`.