docs(instances): revamp api docs

cmd/scw/testdata/test-all-usage-instance-image-create-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create an instance image.
+Create an Instance image from the specified snapshot ID.
 
 USAGE:
   scw instance image create [arg=value ...]
 
 EXAMPLES:
-  Create an image named 'foobar' for x86_64 instances from the given snapshot ID
-    scw instance image create name=foobar snapshot-id=11111111-1111-1111-1111-111111111111 arch=x86_64
+  Create an image named 'foobar' for x86_64 Instances from the specified snapshot ID
+    scw instance server image create name=foobar snapshot-id=11111111-1111-1111-1111-111111111111 arch=x86_64
 
 ARGS:
   [name=<generated>]                           Name of the image
@@ -19,7 +19,7 @@ ARGS:
   [additional-snapshots.{index}.volume-type]   Underlying volume type of the additional snapshot (l_ssd | b_ssd | unified)
   [additional-snapshots.{index}.project-id]    Project ID that own the additional snapshot
   [project-id]                                 Project ID to use. If none is passed the default project ID will be used
-  [tags.{index}]                               The tags of the image
+  [tags.{index}]                               Tags of the image
   [public]                                     True to create a public image
   [organization-id]                            Organization ID to use. If none is passed the default organization ID will be used
   [zone=fr-par-1]                              Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)

cmd/scw/testdata/test-all-usage-instance-image-delete-usage.golden

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete the image with the given ID.
+Delete the image with the specified ID.
 
 USAGE:
   scw instance image delete <image-id ...> [arg=value ...]
 
 EXAMPLES:
-  Delete an image in the default zone with the given ID
+  Delete an image in the default zone with the specified ID
     scw instance image delete 11111111-1111-1111-1111-111111111111
 
-  Delete an image in fr-par-1 zone with the given ID
+  Delete an image in fr-par-1 zone with the specified ID
     scw instance image delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1
 
 ARGS:

cmd/scw/testdata/test-all-usage-instance-image-get-usage.golden

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get details of an image with the given ID.
+Get details of an image with the specified ID.
 
 USAGE:
   scw instance image get <image-id ...> [arg=value ...]
 
 EXAMPLES:
-  Get an image in the default zone with the given ID
+  Get an image in the default zone with the specified ID
     scw instance image get 11111111-1111-1111-1111-111111111111
 
-  Get an image in fr-par-1 zone with the given ID
+  Get an image in fr-par-1 zone with the specified ID
     scw instance image get 11111111-1111-1111-1111-111111111111 zone=fr-par-1
 
 ARGS:

cmd/scw/testdata/test-all-usage-instance-image-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List all images available in an account.
+List all existing Instance images.
 
 USAGE:
   scw instance image list [arg=value ...]

cmd/scw/testdata/test-all-usage-instance-image-usage.golden

@@ -1,18 +1,17 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Images are backups of your instances.
-You can reuse that image to restore your data or create a series of instances with a predefined configuration.
-
-An image is a complete backup of your server including all volumes.
+Images are backups of your Instances.
+One image will contain all of the volumes of your Instance, and can be used to restore your Instance and its data. You can also use it to create a series of Instances with a predefined configuration. 
+To copy not all but only one specified volume of an Instance, you can use the snapshot feature instead.
 
 USAGE:
   scw instance image <command>
 
 AVAILABLE COMMANDS:
-  create      Create an instance image
-  delete      Delete an instance image
-  get         Get an instance image
-  list        List instance images
+  create      Create an Instance image
+  delete      Delete an Instance image
+  get         Get an Instance image
+  list        List Instance images
   update      Update an instance image
 
 WORKFLOW COMMANDS:

cmd/scw/testdata/test-all-usage-instance-ip-create-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Reserve a flexible IP.
+Reserve a flexible IP and attach it to the specified Instance.
 
 USAGE:
   scw instance ip create [arg=value ...]
@@ -12,13 +12,13 @@ EXAMPLES:
   Create an IP in fr-par-1 zone
     scw instance ip create zone=fr-par-1
 
-  Create an IP and attach it to the given server
+  Create an IP and attach it to the specified Instance
     scw instance ip create server=11111111-1111-1111-1111-111111111111
 
 ARGS:
   [project-id]        Project ID to use. If none is passed the default project ID will be used
-  [tags.{index}]      The tags of the IP
-  [server]            UUID of the server you want to attach the IP to
+  [tags.{index}]      Tags of the IP
+  [server]            UUID of the Instance you want to attach the IP to
   [organization-id]   Organization ID to use. If none is passed the default organization ID will be used
   [zone=fr-par-1]     Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 

cmd/scw/testdata/test-all-usage-instance-ip-delete-usage.golden

@@ -1,22 +1,22 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete the IP with the given ID.
+Delete the IP with the specified ID.
 
 USAGE:
   scw instance ip delete <ip ...> [arg=value ...]
 
 EXAMPLES:
-  Delete an IP in the default zone with the given ID
+  Delete an IP in the default zone with the specified ID
     scw instance ip delete 11111111-1111-1111-1111-111111111111
 
-  Delete an IP in fr-par-1 zone with the given ID
+  Delete an IP in fr-par-1 zone with the specified ID
     scw instance ip delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1
 
-  Delete an IP using directly the given IP address
+  Delete an IP using directly the specified IP address
     scw instance ip delete 51.15.253.183
 
 ARGS:
-  ip                The ID or the address of the IP to delete
+  ip                ID or address of the IP to delete
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-instance-ip-get-usage.golden

@@ -1,22 +1,22 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get details of an IP with the given ID or address.
+Get details of an IP with the specified ID or address.
 
 USAGE:
   scw instance ip get <ip ...> [arg=value ...]
 
 EXAMPLES:
-  Get an IP in the default zone with the given ID
+  Get an IP in the default zone with the specified ID
     scw instance ip get 11111111-1111-1111-1111-111111111111
 
-  Get an IP in fr-par-1 zone with the given ID
+  Get an IP in fr-par-1 zone with the specified ID
     scw instance ip get 11111111-1111-1111-1111-111111111111 zone=fr-par-1
 
-  Get an IP using directly the given IP address
+  Get an IP, directly using the specified IP address
     scw instance ip get 51.15.253.183
 
 ARGS:
-  ip                The IP ID or address to get
+  ip                IP ID or address to get
   [zone=fr-par-1]   Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-instance-ip-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List all flexible IPs.
+List all flexible IPs in a specified zone.
 
 USAGE:
   scw instance ip list [arg=value ...]
@@ -13,10 +13,10 @@ EXAMPLES:
     scw instance ip list zone=fr-par-1
 
 ARGS:
-  [project-id]        The project ID the IPs are reserved in
+  [project-id]        Project ID in which the IPs are reserved
   [tags.{index}]      Filter IPs with these exact tags (to filter with several tags, use commas to separate them)
   [name]              Filter on the IP address (Works as a LIKE operation on the IP address)
-  [organization-id]   The organization ID the IPs are reserved in
+  [organization-id]   Organization ID in which the IPs are reserved
   [zone=fr-par-1]     Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2 | all)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-instance-ip-update-usage.golden

@@ -1,18 +1,18 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update a flexible IP.
+Update a flexible IP in the specified zone with the specified ID.
 
 USAGE:
   scw instance ip update <ip ...> [arg=value ...]
 
 EXAMPLES:
-  Update an IP in the default zone with the given ID
+  Update an IP in the default zone with the specified ID
     scw instance ip update 11111111-1111-1111-1111-111111111111 reverse=example.com
 
-  Update an IP in fr-par-1 zone with the given ID
+  Update an IP in fr-par-1 zone with the specified ID
     scw instance ip update 11111111-1111-1111-1111-111111111111 zone=fr-par-1 reverse=example.com
 
-  Update an IP using directly the given IP address
+  Update an IP using directly the specified IP address
     scw instance ip update 51.15.253.183 reverse=example.com
 
 ARGS:

cmd/scw/testdata/test-all-usage-instance-ip-usage.golden

@@ -1,9 +1,9 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-A flexible IP address is an IP address which you hold independently of any server.
-You can attach it to any of your servers and do live migration of the IP address between your servers.
+A flexible IP address is an IP address which you hold independently of any Instance.
+You can attach it to any of your Instances and do live migration of the IP address between your Instances.
 
-Be aware that attaching a flexible IP address to a server will remove the previous public IP address of the server and cut any ongoing public connection to the server.
+Note that attaching a flexible IP address to an Instance will remove the previous public IP address of the Instance and cut any ongoing public connection to the Instance.
 
 USAGE:
   scw instance ip <command>

cmd/scw/testdata/test-all-usage-instance-placement-group-create-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a new placement group.
+Create a new placement group in a specified Availability Zone.
 
 USAGE:
   scw instance placement-group create [arg=value ...]
@@ -9,7 +9,7 @@ EXAMPLES:
   Create a placement group with default name
     scw instance placement-group create
 
-  Create a placement group with the given name
+  Create a placement group with the specified name
     scw instance placement-group create name=foobar
 
   Create an enforced placement group
@@ -27,9 +27,9 @@ EXAMPLES:
 ARGS:
   [name=<generated>]   Name of the placement group
   [project-id]         Project ID to use. If none is passed the default project ID will be used
-  [tags.{index}]       The tags of the placement group
-  [policy-mode]        The operating mode of the placement group (optional | enforced)
-  [policy-type]        The policy type of the placement group (max_availability | low_latency)
+  [tags.{index}]       Tags of the placement group
+  [policy-mode]        Operating mode of the placement group (optional | enforced)
+  [policy-type]        Policy type of the placement group (max_availability | low_latency)
   [organization-id]    Organization ID to use. If none is passed the default organization ID will be used
   [zone=fr-par-1]      Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 

cmd/scw/testdata/test-all-usage-instance-placement-group-delete-usage.golden

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete the given placement group.
+Delete the specified placement group.
 
 USAGE:
   scw instance placement-group delete <placement-group-id ...> [arg=value ...]
 
 EXAMPLES:
-  Delete a placement group in the default zone with the given ID
+  Delete a placement group in the default zone with the specified ID
     scw instance placement-group delete 11111111-1111-1111-1111-111111111111
 
-  Delete a placement group in fr-par-1 zone with the given ID
+  Delete a placement group in fr-par-1 zone with the specified ID
     scw instance placement-group delete 11111111-1111-1111-1111-111111111111 zone=fr-par-1
 
 ARGS:

cmd/scw/testdata/test-all-usage-instance-placement-group-get-servers-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get all servers belonging to the given placement group.
+Get all Instances belonging to the specified placement group.
 
 USAGE:
-  scw instance placement-group get-servers [arg=value ...]
+  scw instance placement-group get-servers <placement-group-id ...> [arg=value ...]
 
 ARGS:
-  placement-group-id   
+  placement-group-id   UUID of the placement group you want to get
   [zone=fr-par-1]      Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-instance-placement-group-get-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the given placement group.
+Get the specified placement group.
 
 USAGE:
   scw instance placement-group get <placement-group-id ...> [arg=value ...]
 
 EXAMPLES:
-  Get a placement group with the given ID
+  Get a placement group with the specified ID
     scw instance placement-group get 6c15f411-3b6f-402d-8eba-ae24ef9254e9
 
 ARGS:

cmd/scw/testdata/test-all-usage-instance-placement-group-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List all placement groups.
+List all placement groups in a specified Availability Zone.
 
 USAGE:
   scw instance placement-group list [arg=value ...]
@@ -9,14 +9,14 @@ EXAMPLES:
   List all placement groups in the default zone
     scw instance placement-group list
 
-  List placement groups that match a given name ('cluster1' will return 'cluster100' and 'cluster1' but not 'foo')
+  List placement groups that match a specified name ('cluster1' will return 'cluster100' and 'cluster1' but not 'foo')
     scw instance placement-group list name=cluster1
 
 ARGS:
-  [project-id]        List only placement groups of this project ID
+  [project-id]        List only placement groups of this Project ID
   [tags.{index}]      List placement groups with these exact tags (to filter with several tags, use commas to separate them)
   [name]              Filter placement groups by name (for eg. "cluster1" will return "cluster100" and "cluster1" but not "foo")
-  [organization-id]   List only placement groups of this organization ID
+  [organization-id]   List only placement groups of this Organization ID
   [zone=fr-par-1]     Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2 | all)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-instance-placement-group-set-servers-usage.golden

@@ -1,17 +1,17 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Set all servers belonging to the given placement group.
+Set all Instances belonging to the specified placement group.
 
 USAGE:
   scw instance placement-group set-servers [arg=value ...]
 
 EXAMPLES:
-  Update the complete set of instances in a given placement group. (All instances must be down)
+  Update the complete set of Instances in a specified placement group (all Instances must be shut down)
     scw instance placement-group set-servers placement-group-id=ced0fd4d-bcf0-4479-85b6-7027e54456e6 servers.0=5a250608-24ec-4c31-9631-b3ded8c861cb servers.1=e54fd249-0787-4794-ab14-af6ee74df274
 
 ARGS:
-  placement-group-id   
-  [servers.{index}]    
+  placement-group-id   UUID of the placement group you want to set
+  servers.{index}      An array of the Instances' UUIDs you want to configure
   [zone=fr-par-1]      Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS:

cmd/scw/testdata/test-all-usage-instance-placement-group-set-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Set all parameters of the given placement group.
+Set all parameters of the specified placement group.
 
 USAGE:
   scw instance placement-group set [arg=value ...]

cmd/scw/testdata/test-all-usage-instance-placement-group-update-servers-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Update all servers belonging to the given placement group.
+Update all Instances belonging to the specified placement group.
 
 USAGE:
   scw instance placement-group update-servers [arg=value ...]
 
 ARGS:
-  placement-group-id   UUID of the placement group
-  servers.{index}      
+  placement-group-id   UUID of the placement group you want to update
+  servers.{index}      An array of the Instances' UUIDs you want to configure
   [zone=fr-par-1]      Zone to target. If none is passed will use default zone from the config (fr-par-1 | fr-par-2 | fr-par-3 | nl-ams-1 | nl-ams-2 | pl-waw-1 | pl-waw-2)
 
 FLAGS: