docs(cockpit): revamp api documentation

cmd/scw/testdata/test-all-usage-cockpit-alert-disable-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Disable managed alerts.
+Disable the sending of managed alerts for the specified Project's Cockpit.
 
 USAGE:
   scw cockpit alert disable [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-alert-enable-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Enable managed alerts.
+Enable the sending of managed alerts for the specified Project's Cockpit.
 
 USAGE:
   scw cockpit alert enable [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-alert-test-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Trigger a test alert to all receivers.
+Trigger a test alert to all of the Cockpit's receivers.
 
 USAGE:
   scw cockpit alert test [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-cockpit-activate-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Activate a cockpit associated with the given project ID.
+Activate the Cockpit of the specified Project ID.
 
 USAGE:
   scw cockpit cockpit activate [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-cockpit-deactivate-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Deactivate a cockpit associated with the given project ID.
+Deactivate the Cockpit of the specified Project ID.
 
 USAGE:
   scw cockpit cockpit deactivate [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-cockpit-get-metrics-usage.golden

@@ -1,15 +1,15 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the cockpit metrics with the given project ID.
+Get metrics from your Cockpit with the specified Project ID.
 
 USAGE:
   scw cockpit cockpit get-metrics [arg=value ...]
 
 ARGS:
   [project-id]    Project ID to use. If none is passed the default project ID will be used
-  [start-date]    Start date
-  [end-date]      End date
-  [metric-name]   Metric name
+  [start-date]    Desired time range's start date for the metrics
+  [end-date]      Desired time range's end date for the metrics
+  [metric-name]   Name of the metric requested
 
 FLAGS:
   -h, --help   help for get-metrics

cmd/scw/testdata/test-all-usage-cockpit-cockpit-get-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the cockpit associated with the given project ID.
+Retrieve the Cockpit of the specified Project ID.
 
 USAGE:
   scw cockpit cockpit get [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-cockpit-reset-grafana-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Reset the Grafana of your cockpit associated with the given project ID.
+Reset your Cockpit's Grafana associated with the specified Project ID.
 
 USAGE:
   scw cockpit cockpit reset-grafana [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-cockpit-usage.golden

@@ -6,11 +6,11 @@ USAGE:
   scw cockpit cockpit <command>
 
 AVAILABLE COMMANDS:
-  activate      Activate a cockpit
-  deactivate    Deactivate a cockpit
-  get           Get cockpit
-  get-metrics   Get cockpit metrics
-  reset-grafana Reset Grafana
+  activate      Activate a Cockpit
+  deactivate    Deactivate a Cockpit
+  get           Get a Cockpit
+  get-metrics   Get Cockpit metrics
+  reset-grafana Reset a Grafana
 
 WORKFLOW COMMANDS:
   wait          Wait for a cockpit to reach a stable state (installation)

cmd/scw/testdata/test-all-usage-cockpit-contact-create-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create an alert contact point for the default receiver.
+Create a contact point to receive alerts for the default receiver.
 
 USAGE:
   scw cockpit contact create [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-contact-delete-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete an alert contact point for the default receiver.
+Delete a contact point for the default receiver.
 
 USAGE:
   scw cockpit contact delete [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-contact-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List alert contact points associated with the given cockpit ID.
+Get a list of contact points for the Cockpit associated with the specified Project ID.
 
 USAGE:
   scw cockpit contact list [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-contact-usage.golden

@@ -6,9 +6,9 @@ USAGE:
   scw cockpit contact <command>
 
 AVAILABLE COMMANDS:
-  create      Create an alert contact point
+  create      Create a contact point
   delete      Delete an alert contact point
-  list        List alert contact points
+  list        List contact points
 
 FLAGS:
   -h, --help   help for contact

cmd/scw/testdata/test-all-usage-cockpit-grafana-user-create-usage.golden

@@ -1,14 +1,14 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a grafana user for your grafana instance.
+Create a Grafana user for your Cockpit's Grafana instance. Make sure you save the automatically-generated password and the Grafana user ID.
 
 USAGE:
   scw cockpit grafana-user create [arg=value ...]
 
 ARGS:
   [project-id]   Project ID to use. If none is passed the default project ID will be used
-  [login]        
-  [role]          (unknown_role | editor | viewer)
+  [login]        Username of the Grafana user
+  [role]         Role assigned to the Grafana user (unknown_role | editor | viewer)
 
 FLAGS:
   -h, --help   help for create

cmd/scw/testdata/test-all-usage-cockpit-grafana-user-delete-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete a grafana user from your grafana instance.
+Delete a Grafana user from a Grafana instance, specified by the Cockpit's Project ID and the Grafana user ID.
 
 USAGE:
   scw cockpit grafana-user delete [arg=value ...]
 
 ARGS:
   [project-id]      Project ID to use. If none is passed the default project ID will be used
-  grafana-user-id   
+  grafana-user-id   ID of the Grafana user
 
 FLAGS:
   -h, --help   help for delete

cmd/scw/testdata/test-all-usage-cockpit-grafana-user-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List grafana users who are able to connect to your grafana instance.
+Get a list of Grafana users who are able to connect to the Cockpit's Grafana instance.
 
 USAGE:
   scw cockpit grafana-user list [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-grafana-user-reset-password-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Reset the Grafana user password from your grafana instance.
+Reset a Grafana user's password specified by the Cockpit's Project ID and the Grafana user ID.
 
 USAGE:
   scw cockpit grafana-user reset-password [arg=value ...]
 
 ARGS:
   [project-id]      Project ID to use. If none is passed the default project ID will be used
-  grafana-user-id   
+  grafana-user-id   ID of the Grafana user
 
 FLAGS:
   -h, --help   help for reset-password

cmd/scw/testdata/test-all-usage-cockpit-grafana-user-usage.golden

@@ -6,10 +6,10 @@ USAGE:
   scw cockpit grafana-user <command>
 
 AVAILABLE COMMANDS:
-  create         Create a grafana user
-  delete         Delete a grafana user
-  list           List grafana users
-  reset-password Reset Grafana user password
+  create         Create a Grafana user
+  delete         Delete a Grafana user
+  list           List Grafana users
+  reset-password Reset a Grafana user's password
 
 FLAGS:
   -h, --help   help for grafana-user

cmd/scw/testdata/test-all-usage-cockpit-plan-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List all pricing plans.
+Get a list of all pricing plans available.
 
 USAGE:
   scw cockpit plan list [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-plan-select-usage.golden

@@ -1,13 +1,13 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Select the wanted pricing plan.
+Select your chosen pricing plan for your Cockpit, specifying the Cockpit's Project ID and the pricing plan's ID in the request.
 
 USAGE:
   scw cockpit plan select [arg=value ...]
 
 ARGS:
   [project-id]   Project ID to use. If none is passed the default project ID will be used
-  [plan-id]      
+  [plan-id]      ID of the pricing plan
 
 FLAGS:
   -h, --help   help for select

cmd/scw/testdata/test-all-usage-cockpit-plan-usage.golden

@@ -6,7 +6,7 @@ USAGE:
   scw cockpit plan <command>
 
 AVAILABLE COMMANDS:
-  list        List plans
+  list        List pricing plans
   select      Select pricing plan
 
 FLAGS:

cmd/scw/testdata/test-all-usage-cockpit-token-create-usage.golden

@@ -1,20 +1,20 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Create a token associated with the given project ID.
+Create a token associated with the specified Project ID.
 
 USAGE:
   scw cockpit token create [arg=value ...]
 
 ARGS:
   [project-id]                   Project ID to use. If none is passed the default project ID will be used
-  [name=<generated>]             
-  [scopes.query-metrics]         
-  [scopes.write-metrics]         
-  [scopes.setup-metrics-rules]   
-  [scopes.query-logs]            
-  [scopes.write-logs]            
-  [scopes.setup-logs-rules]      
-  [scopes.setup-alerts]          
+  [name=<generated>]             Name of the token
+  [scopes.query-metrics]         Permission to fetch metrics
+  [scopes.write-metrics]         Permission to write metrics
+  [scopes.setup-metrics-rules]   Permission to setup metrics rules
+  [scopes.query-logs]            Permission to fetch logs
+  [scopes.write-logs]            Permission to write logs
+  [scopes.setup-logs-rules]      Permission to setup logs rules
+  [scopes.setup-alerts]          Permission to setup alerts
 
 FLAGS:
   -h, --help   help for create

cmd/scw/testdata/test-all-usage-cockpit-token-delete-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Delete the token associated with the given ID.
+Delete the token associated with the specified token ID.
 
 USAGE:
   scw cockpit token delete [arg=value ...]
 
 ARGS:
-  token-id   
+  token-id   ID of the token
 
 FLAGS:
   -h, --help   help for delete

cmd/scw/testdata/test-all-usage-cockpit-token-get-usage.golden

@@ -1,12 +1,12 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Get the token associated with the given ID.
+Retrieve the token associated with the specified token ID.
 
 USAGE:
   scw cockpit token get <token-id ...> [arg=value ...]
 
 ARGS:
-  token-id   
+  token-id   ID of the token
 
 FLAGS:
   -h, --help   help for get

cmd/scw/testdata/test-all-usage-cockpit-token-list-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-List tokens associated with the given project ID.
+Get a list of tokens associated with the specified Project ID.
 
 USAGE:
   scw cockpit token list [arg=value ...]

cmd/scw/testdata/test-all-usage-cockpit-token-usage.golden

@@ -7,8 +7,8 @@ USAGE:
 
 AVAILABLE COMMANDS:
   create      Create a token
-  delete      Delete token
-  get         Get token
+  delete      Delete a token
+  get         Get a token
   list        List tokens
 
 FLAGS:

cmd/scw/testdata/test-all-usage-cockpit-usage.golden

@@ -1,6 +1,6 @@
 🎲🎲🎲 EXIT CODE: 0 🎲🎲🎲
 🟥🟥🟥 STDERR️️ 🟥🟥🟥️
-Cockpit API.
+Cockpit's API allows you to activate your Cockpit on your Projects. Scaleway's Cockpit stores metrics and logs and provides a dedicated Grafana for dashboarding to visualize them.
 
 USAGE:
   scw cockpit <command>