docs: re-word on docstrings [ci skip]

cli/app/app.go

@@ -9,7 +9,7 @@ var AppCommand = cli.Command{
 	Aliases:     []string{"a"},
 	Usage:       "Manage apps",
 	ArgsUsage:   "<domain>",
-	Description: "This command provides functionality for managing the life cycle of your apps",
+	Description: "Functionality for managing the life cycle of your apps",
 	Subcommands: []cli.Command{
 		appNewCommand,
 		appConfigCommand,

cli/app/backup.go

@@ -45,7 +45,7 @@ var appBackupCommand = cli.Command{
 	Before:       internal.SubCommandBefore,
 	BashComplete: autocomplete.AppNameComplete,
 	Description: `
-This command runs an app backup.
+Run an app backup.
 
 A backup command and pre/post hook commands are defined in the recipe
 configuration. Abra reads this configuration and run the comands in the context

cli/app/cmd.go

@@ -45,7 +45,7 @@ var appCmdCommand = cli.Command{
 	Aliases: []string{"cmd"},
 	Usage:   "Run app commands",
 	Description: `
-This command runs app specific commands.
+Run an app specific command.
 
 These commands are bash functions, defined in the abra.sh of the recipe itself.
 They can be run within the context of a service (e.g. app) or locally on your

cli/app/cp.go

@@ -30,7 +30,7 @@ var appCpCommand = cli.Command{
 	Before: internal.SubCommandBefore,
 	Usage:  "Copy files to/from a running app service",
 	Description: `
-This command supports copying files to and from any app service file system.
+Copy files to and from any app service file system.
 
 If you want to copy a myfile.txt to the root of the app service:
 

cli/app/deploy.go

@@ -21,9 +21,8 @@ var appDeployCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command deploys an app. It does not support incrementing the version of a
+Deploy an app. It does not support incrementing the version of a deployed app,
-deployed app, for this you need to look at the "abra app upgrade <domain>"
+for this you need to look at the "abra app upgrade <domain>" command.
-command.
 
 You may pass "--force" to re-deploy the same version again. This can be useful
 if the container runtime has gotten into a weird state.

cli/app/errors.go

@@ -25,7 +25,7 @@ var appErrorsCommand = cli.Command{
 	Usage:     "List errors for a deployed app",
 	ArgsUsage: "<domain>",
 	Description: `
-This command lists errors for a deployed app.
+List errors for a deployed app.
 
 This is a best-effort implementation and an attempt to gather a number of tips
 & tricks for finding errors together into one convenient command. When an app

cli/app/list.go

@@ -62,8 +62,8 @@ var appListCommand = cli.Command{
 	Aliases: []string{"ls"},
 	Usage:   "List all managed apps",
 	Description: `
-This command looks at your local file system listing of apps and servers (e.g.
+Read the local file system listing of apps and servers (e.g. ~/.abra/) to
-in ~/.abra/) to generate a report of all your apps.
+generate a report of all your apps.
 
 By passing the "--status/-S" flag, you can query all your servers for the
 actual live deployment status. Depending on how many servers you manage, this

cli/app/new.go

@@ -7,8 +7,8 @@ import (
 )
 
 var appNewDescription = `
-This command takes a recipe and uses it to create a new app. This new app
+Take a recipe and uses it to create a new app. This new app configuration is
-configuration is stored in your ~/.abra directory under the appropriate server.
+stored in your ~/.abra directory under the appropriate server.
 
 This command does not deploy your app for you. You will need to run "abra app
 deploy <domain>" to do so.

cli/app/ps.go

@@ -25,7 +25,7 @@ var appPsCommand = cli.Command{
 	Aliases:     []string{"p"},
 	Usage:       "Check app status",
 	ArgsUsage:   "<domain>",
-	Description: "This command shows a more detailed status output of a specific deployed app.",
+	Description: "Show a more detailed status output of a specific deployed app",
 	Flags: []cli.Flag{
 		internal.WatchFlag,
 		internal.DebugFlag,

cli/app/restore.go

@@ -37,7 +37,7 @@ var appRestoreCommand = cli.Command{
 	Before:       internal.SubCommandBefore,
 	BashComplete: autocomplete.AppNameComplete,
 	Description: `
-This command runs an app restore.
+Run an app restore.
 
 Pre/post hook commands are defined in the recipe configuration. Abra reads this
 configuration and run the comands in the context of the service before

cli/app/upgrade.go

@@ -32,8 +32,8 @@ var appUpgradeCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command supports upgrading an app. You can use it to choose and roll out a
+Upgrade an app. You can use it to choose and roll out a new upgrade to an
-new upgrade to an existing app.
+existing app.
 
 This command specifically supports incrementing the version of running apps, as
 opposed to "abra app deploy <domain>" which will not change the version of a

cli/app/version.go

@@ -41,9 +41,9 @@ var appVersionCommand = cli.Command{
 	Before: internal.SubCommandBefore,
 	Usage:  "Show app versions",
 	Description: `
-This command shows all information about versioning related to a deployed app.
+Show all information about versioning related to a deployed app. This includes
-This includes the individual image names, tags and digests. But also the Co-op
+the individual image names, tags and digests. But also the Co-op Cloud recipe
-Cloud recipe version.
+version.
 `,
 	Action: func(c *cli.Context) error {
 		app := internal.ValidateApp(c)

cli/catalogue/catalogue.go

@@ -71,14 +71,14 @@ var catalogueGenerateCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command generates a new copy of the recipe catalogue which can be found on:
+Generate a new copy of the recipe catalogue which can be found on:
 
     https://recipes.coopcloud.tech (website that humans read)
     https://recipes.coopcloud.tech/recipes.json (JSON that Abra reads)
 
 It polls the entire git.coopcloud.tech/coop-cloud/... recipe repository
-listing, parses README.md and git tags of those repositories to produce recipe
+listing, parses README.md and git tags to produce recipe metadata which is
-metadata and produces a recipes JSON file.
+loaded into the catalogue JSON file.
 
 It is possible to generate new metadata for a single recipe by passing
 <recipe>. The existing local catalogue will be updated, not overwritten.

cli/cli.go

@@ -27,19 +27,13 @@ var AutoCompleteCommand = cli.Command{
 	Aliases: []string{"ac"},
 	Usage:   "Configure shell autocompletion (recommended)",
 	Description: `
-This command helps set up autocompletion in your shell by downloading the
+Set up auto-completion in your shell by downloading the relevant files and
-relevant autocompletion files and laying out what additional information must
+laying out what additional information must be loaded. Supported shells are as
-be loaded.
+follows: bash, fizsh & zsh.
 
 Example:
 
     abra autocomplete bash
-
-Supported shells are as follows:
-
-		fizsh
-		zsh
-    bash
 `,
 	ArgsUsage: "<shell>",
 	Flags: []cli.Flag{
@@ -86,7 +80,7 @@ Supported shells are as follows:
 		switch shellType {
 		case "bash":
 			fmt.Println(fmt.Sprintf(`
-# Run the following commands to install autocompletion
+# Run the following commands to install auto-completion
 sudo mkdir /etc/bash_completion.d/
 sudo cp %s /etc/bash_completion.d/abra
 echo "source /etc/bash_completion.d/abra" >> ~/.bashrc
@@ -94,7 +88,7 @@ echo "source /etc/bash_completion.d/abra" >> ~/.bashrc
 `, autocompletionFile))
 		case "zsh":
 			fmt.Println(fmt.Sprintf(`
-# Run the following commands to install autocompletion
+# Run the following commands to install auto-completion
 sudo mkdir /etc/zsh/completion.d/
 sudo cp %s /etc/zsh/completion.d/abra
 echo "PROG=abra\n_CLI_ZSH_AUTOCOMPLETE_HACK=1\nsource /etc/zsh/completion.d/abra" >> ~/.zshrc
@@ -112,13 +106,11 @@ var UpgradeCommand = cli.Command{
 	Aliases: []string{"u"},
 	Usage:   "Upgrade Abra itself",
 	Description: `
-This command allows you to upgrade Abra in-place with the latest stable or
+Upgrade Abra in-place with the latest stable or release candidate.
-release candidate.
 
-If you would like to install the latest release candidate, please pass the
+Pass "-r/--rc" to install the latest release candidate. Please bear in mind
-"-r/--rc" option. Please bear in mind that the latest release candidate may
+that it may contain catastrophic bugs. Thank you very much for the testing
-have some catastrophic bugs contained in it. In any case, thank you very much
+efforts!
-for the testing efforts!
 `,
 	Flags: []cli.Flag{internal.RCFlag},
 	Action: func(c *cli.Context) error {

cli/recipe/new.go

@@ -41,9 +41,9 @@ var recipeNewCommand = cli.Command{
 	Usage:     "Create a new recipe",
 	ArgsUsage: "<recipe>",
 	Description: `
-This command creates a new recipe.
+Create a new recipe.
 
-Abra uses our built-in example repository which is available here:
+Abra uses the built-in example repository which is available here:
 
     https://git.coopcloud.tech/coop-cloud/example
 

cli/recipe/recipe.go

@@ -13,7 +13,8 @@ var RecipeCommand = cli.Command{
 	Description: `
 A recipe is a blueprint for an app. It is a bunch of config files which
 describe how to deploy and maintain an app. Recipes are maintained by the Co-op
-Cloud community and you can use Abra to read them and create apps for you.
+Cloud community and you can use Abra to read them, deploy them and create apps
+for you.
 
 Anyone who uses a recipe can become a maintainer. Maintainers typically make
 sure the recipe is in good working order and the config upgraded in a timely

cli/recipe/release.go

@@ -27,17 +27,16 @@ var recipeReleaseCommand = cli.Command{
 	Usage:     "Release a new recipe version",
 	ArgsUsage: "<recipe> [<version>]",
 	Description: `
-This command is used to specify a new version of a recipe. These versions are
+Create a new version of a recipe. These versions are then published on the
-then published on the Co-op Cloud recipe catalogue. These versions take the
+Co-op Cloud recipe catalogue. These versions take the following form:
-following form:
 
     a.b.c+x.y.z
 
-Where the "a.b.c" part is a semantic version determined by the maintainer. And
+Where the "a.b.c" part is a semantic version determined by the maintainer. The
-the "x.y.z" part is the image tag of the recipe "app" service (the main
+"x.y.z" part is the image tag of the recipe "app" service (the main container
-container which contains the software to be used).
+which contains the software to be used, by naming convention).
 
-We maintain a semantic versioning scheme ("a.b.c") alongside the libre app
+We maintain a semantic versioning scheme ("a.b.c") alongside the recipe
 versioning scheme ("x.y.z") in order to maximise the chances that the nature of
 recipe updates are properly communicated. I.e. developers of an app might
 publish a minor version but that might lead to changes in the recipe which are

cli/recipe/sync.go

@@ -31,8 +31,8 @@ var recipeSyncCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command will generate labels for the main recipe service (i.e. by
+Generate labels for the main recipe service (i.e. by convention, the service
-convention, the service named 'app') which corresponds to the following format:
+named "app") which corresponds to the following format:
 
     coop-cloud.${STACK_NAME}.version=<version>
 

cli/recipe/upgrade.go

@@ -31,9 +31,9 @@ var recipeUpgradeCommand = cli.Command{
 	Aliases: []string{"u"},
 	Usage:   "Upgrade recipe image tags",
 	Description: `
-This command reads and attempts to parse all image tags within the given
+Parse all image tags within the given <recipe> configuration and prompt with
-<recipe> configuration and prompt with more recent tags to upgrade to. It will
+more recent tags to upgrade to. It will update the relevant compose file tags
-update the relevant compose file tags on the local file system.
+on the local file system.
 
 Some image tags cannot be parsed because they do not follow some sort of
 semver-like convention. In this case, all possible tags will be listed and it

cli/record/list.go

@@ -25,8 +25,8 @@ var RecordListCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command lists all domain name records managed by a 3rd party provider for
+List all domain name records managed by a 3rd party provider for a specific
-a specific zone.
+zone.
 
 You must specify a zone (e.g. example.com) under which your domain name records
 are listed. This zone must already be created on your provider account.

cli/record/new.go

@@ -33,7 +33,7 @@ var RecordNewCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command creates a new domain name record for a specific zone.
+Create a new domain name record for a specific zone.
 
 You must specify a zone (e.g. example.com) under which your domain name records
 are listed. This zone must already be created on your provider account.

cli/record/record.go

@@ -11,9 +11,9 @@ var RecordCommand = cli.Command{
 	Aliases:   []string{"rc"},
 	ArgsUsage: "<record>",
 	Description: `
-This command supports managing domain name records via 3rd party providers such
+Manage domain name records via 3rd party providers such as Gandi DNS. It
-as Gandi DNS. It supports listing, creating and removing all types of records
+supports listing, creating and removing all types of records that you might
-that you might need for managing Co-op Cloud apps.
+need for managing Co-op Cloud apps.
 
 The following providers are supported:
 

cli/record/remove.go

@@ -30,7 +30,7 @@ var RecordRemoveCommand = cli.Command{
 	},
 	Before: internal.SubCommandBefore,
 	Description: `
-This command removes a domain name record for a specific zone.
+Remove a domain name record for a specific zone.
 
 It uses the type of record and name to match existing records and choose one
 for deletion. You must specify a zone (e.g. example.com) under which your

cli/server/add.go

@@ -28,8 +28,8 @@ import (
 var (
 	dockerInstallMsg = `
 A docker installation cannot be found on %s. This is a required system
-dependency for running Co-op Cloud on your server. If you would like, Abra can
+dependency for running Co-op Cloud apps on your server. If you would like, Abra
-attempt to install Docker for you using the upstream non-interactive
+can attempt to install Docker for you using the upstream non-interactive
 installation script.
 
 See the following documentation for more:
@@ -246,7 +246,7 @@ Abra was unable to bootstrap Docker, see below for logs:
 
 %s
 
-If nothing works, you try running the Docker install script manually on your server:
+If nothing works, you can try running the Docker install script manually on your server:
 
     wget -O- https://get.docker.com | bash
 
@@ -276,7 +276,7 @@ Abra was unable to bootstrap Docker, see below for logs:
 
 %s
 
-This could be due to a number of things but one of the most common is that your
+This could be due to several reasons. One of the most common is that your
 server user account does not have sudo access, and if it does, you need to pass
 "--ask-sudo-pass" in order to supply Abra with your password.
 
@@ -370,9 +370,9 @@ var serverAddCommand = cli.Command{
 	Aliases: []string{"a"},
 	Usage:   "Add a server to your configuration",
 	Description: `
-This command adds a new server to your configuration so that it can be managed
+Add a new server to your configuration so that it can be managed by Abra. This
-by Abra. This command can also provision your server ("--provision/-p") with a
+command can also provision your server ("--provision/-p") with a Docker
-Docker installation so that it is capable of hosting Co-op Cloud apps.
+installation so that it is capable of hosting Co-op Cloud apps.
 
 Abra will default to expecting that you have a running ssh-agent and are using
 SSH keys to connect to your new server. Abra will also read your SSH config
@@ -385,9 +385,9 @@ password. "--ask-sudo-pass" may be passed if you run your provisioning commands
 via sudo privilege escalation.
 
 The <domain> argument must be a publicy accessible domain name which points to
-your server. You should working SSH access to this server already, Abra will
+your server. You should have working SSH access to this server already, Abra
-assume port 22 and will use your current system username to make an initial
+will assume port 22 and will use your current system username to make an
-connection. You can use the <user> and <port> arguments to adjust this.
+initial connection. You can use the <user> and <port> arguments to adjust this.
 
 Example:
 

cli/server/new.go

@@ -99,9 +99,10 @@ You can access this new VPS via SSH using the following command:
     ssh root@%s
 
 Please note, this server is not managed by Abra yet (i.e. "abra server ls" will
-not list this server)! You will need to assign a domain name record ("abra
+not list this server)! You will need to assign a domain name record (manually
-record new") and add the server to your Abra configuration ("abra server add")
+or by using "abra record new") and add the server to your Abra configuration
-to have a working server that you can deploy Co-op Cloud apps to.
+("abra server add") to have a working server that you can deploy Co-op Cloud
+apps to.
 
 When setting up domain name records, you probably want to set up the following
 2 A records. This supports deploying apps to your root domain (e.g.
@@ -110,7 +111,6 @@ bar.example.com).
 
     @  1800 IN A %s
     *  1800 IN A %s
-
 	`,
 		internal.HetznerCloudName, ip, rootPassword,
 		ip, ip, ip,
@@ -181,9 +181,10 @@ address. You can learn all about how to get SSH access to your new Capsul on:
     %s/about-ssh
 
 Please note, this server is not managed by Abra yet (i.e. "abra server ls" will
-not list this server)! You will need to assign a domain name record ("abra
+not list this server)! You will need to assign a domain name record (manually
-record new") and add the server to your Abra configuration ("abra server add")
+or by using "abra record new") and add the server to your Abra configuration
-to have a working server that you can deploy Co-op Cloud apps to.
+("abra server add") to have a working server that you can deploy Co-op Cloud
+apps to.
 
 When setting up domain name records, you probably want to set up the following
 2 A records. This supports deploying apps to your root domain (e.g.
@@ -192,7 +193,6 @@ bar.example.com).
 
     @  1800 IN A <your-capsul-ip>
     *  1800 IN A <your-capsul-ip>
-
 	`, internal.CapsulName, resp.ID, internal.CapsulInstanceURL))
 
 	return nil
@@ -203,7 +203,7 @@ var serverNewCommand = cli.Command{
 	Aliases: []string{"n"},
 	Usage:   "Create a new server using a 3rd party provider",
 	Description: `
-This command creates a new server via a 3rd party provider.
+Create a new server via a 3rd party provider.
 
 The following providers are supported:
 
@@ -217,8 +217,6 @@ You may invoke this command in "wizard" mode and be prompted for input:
 API tokens are read from the environment if specified, e.g.
 
     export HCLOUD_TOKEN=...
-
-Where "$provider_TOKEN" is the expected env var format.
 `,
 	Flags: []cli.Flag{
 		internal.DebugFlag,

cli/server/remove.go

@@ -104,7 +104,7 @@ var serverRemoveCommand = cli.Command{
 	ArgsUsage: "[<server>]",
 	Usage:     "Remove a managed server",
 	Description: `
-This command removes a server from Abra management.
+Remova a server from Abra management.
 
 Depending on whether you used a 3rd party provider to create this server ("abra
 server new"), you can also destroy the virtual server as well. Pass

cli/server/server.go

@@ -10,13 +10,12 @@ var ServerCommand = cli.Command{
 	Aliases: []string{"s"},
 	Usage:   "Manage servers",
 	Description: `
-These commands support creating, managing and removing servers using 3rd party
+Create, manage and remove servers using 3rd party integrations. 
-integrations. 
 
 Servers can be created from scratch using the "abra server new" command. If you
 already have a server, you can add it to your configuration using "abra server
 add". Abra can provision servers so that they are ready to deploy Co-op Cloud
-apps, see available flags on "server add" for more.
+recipes, see available flags on "abra server add" for more.
 `,
 	Subcommands: []cli.Command{
 		serverNewCommand,