docs(instances): revamp api docs (#2974)

Co-authored-by: Rémy Léone <rleone@scaleway.com>

Author: scaleway-bot

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: