Update volume command help docs (#2922)

* update volume command help docs

* typo

* try fixing strings

* i guess you can't just omit long

* whitespace

* test format fix

* fix formatting

* more fixes

* test rm long desc

* abort lol

internal/command/volumes/create.go

@@ -22,11 +22,11 @@ import (
 
 func newCreate() *cobra.Command {
 	const (
-		long = `Create new volume for app. --region flag must be included to specify
-region the volume exists in. --size flag is optional, defaults to 3,
-sets the size as the number of gigabytes the volume will consume.`
+		short = "Create a new volume for an app."
 
-		short = "Create new volume for app"
+		long = short + ` Volumes are persistent storage for
+		Fly Machines. The default size is 3 GB. Learn how to add a volume to
+		your app: https://fly.io/docs/apps/volume-storage/`
 
 		usage = "create <volumename>"
 	)
@@ -46,28 +46,28 @@ sets the size as the number of gigabytes the volume will consume.`
 			Name:        "size",
 			Shorthand:   "s",
 			Default:     3,
-			Description: "Size of volume in gigabytes",
+			Description: "The size of volume in gigabytes. The default is 3.",
 		},
 		flag.Bool{
 			Name:        "no-encryption",
-			Description: "Do not encrypt the volume contents",
+			Description: "Do not encrypt the volume contents. Volume contents are encrypted by default.",
 			Default:     false,
 		},
 		flag.Bool{
 			Name:        "require-unique-zone",
-			Description: "Require volume to be placed in separate hardware zone from existing volumes",
+			Description: "Place the volume in a separate hardware zone from existing volumes. This is the default.",
 			Default:     true,
 		},
 		flag.String{
 			Name:        "snapshot-id",
-			Description: "Create volume from a specified snapshot",
+			Description: "Create the volume from the specified snapshot",
 		},
 		flag.Yes(),
 		flag.Int{
 			Name:        "count",
 			Shorthand:   "n",
 			Default:     1,
-			Description: "Number of volumes to create",
+			Description: "The number of volumes to create",
 		},
 		flag.VMSizeFlags,
 	)
@@ -179,7 +179,7 @@ func confirmVolumeCreate(ctx context.Context, appName string) (bool, error) {
 	io := iostreams.FromContext(ctx)
 	colorize := io.ColorScheme()
 
-	const msg = "Warning! Individual volumes are pinned to individual hosts. You should create two or more volumes per application. You will have downtime if you only create one. Learn more at https://fly.io/docs/reference/volumes/"
+	const msg = "Warning! Every volume is pinned to a specific physical host. You should create two or more volumes per application to avoid downtime. Learn more at https://fly.io/docs/reference/volumes/"
 	fmt.Fprintln(io.ErrOut, colorize.Red(msg))
 
 	switch confirmed, err := prompt.Confirm(ctx, "Do you still want to use the volumes feature?"); {

internal/command/volumes/destroy.go

@@ -19,9 +19,9 @@ import (
 
 func newDestroy() *cobra.Command {
 	const (
-		long = `Destroy a volume`
+		short = "Destroy a volume."
 
-		short = "Destroy a volume"
+		long = short + " When you destroy a volume, you permanently delete all its data."
 	)
 
 	cmd := command.New("destroy [id]", short, long, runDestroy,
@@ -89,7 +89,7 @@ func runDestroy(ctx context.Context) error {
 		return fmt.Errorf("failed destroying volume: %w", err)
 	}
 
-	fmt.Fprintf(io.Out, "Destroyed volume %s from %s\n", volID, data.Name)
+	fmt.Fprintf(io.Out, "Destroyed volume ID: %s name: %s\n", volID, data.Name)
 
 	return nil
 }
@@ -121,7 +121,7 @@ func confirmVolumeDelete(ctx context.Context, volID string) (bool, error) {
 
 	var msg = "Deleting a volume is not reversible."
 	if matches <= 2 {
-		msg = fmt.Sprintf("Warning! Individual volumes are pinned to individual hosts. You should create two or more volumes per application. Deleting this volume will leave you with %d volume(s) for this application, and it is not reversible.  Learn more at https://fly.io/docs/reference/volumes/", matches-1)
+		msg = fmt.Sprintf("Warning! Every volume is pinned to a specific physical host. You should create two or more volumes per application. Deleting this volume will leave you with %d volume(s) for this application, and it is not reversible.  Learn more at https://fly.io/docs/reference/volumes/", matches-1)
 	}
 	fmt.Fprintln(io.ErrOut, colorize.Red(msg))
 

internal/command/volumes/extend.go

@@ -22,11 +22,9 @@ import (
 
 func newExtend() *cobra.Command {
 	const (
-		long = `Extends a target volume to the size specified. The instance is automatically restarted for Nomad (V1) apps.
-		Most Machines (V2 apps) don't require a restart. Older Machines get a message to manually restart the Machine
-		to increase the size of the FS.`
+		short = "Extend a volume to the specified size."
 
-		short = "Extend a target volume"
+		long = short + ` Most Machines don't require a restart. Some older Machines get a message to manually restart the Machine to increase the size of the file system.`
 
 		usage = "extend [id]"
 	)
@@ -132,9 +130,9 @@ func runExtend(ctx context.Context) error {
 
 	if app.PlatformVersion == "machines" {
 		if needsRestart {
-			fmt.Fprintln(out, colorize.Yellow("You will need to stop and start your machine to increase the size of the FS"))
+			fmt.Fprintln(out, colorize.Yellow("You will need to stop and start your Machine to increase the size of the file system"))
 		} else {
-			fmt.Fprintln(out, colorize.Green("Your machine got its volume size extended without needing a restart"))
+			fmt.Fprintln(out, colorize.Green("Your Machine got its volume size extended without needing a restart"))
 		}
 	}
 

internal/command/volumes/fork.go

@@ -20,8 +20,10 @@ import (
 
 func newFork() *cobra.Command {
 	const (
-		long  = `Volume forking creates an independent copy of a storage volume for backup, testing, and experimentation without altering the original data.`
-		short = "Forks the specified volume"
+		short = "Fork the specified volume."
+
+		long = short + ` Volume forking creates an independent copy of a storage volume for backup, testing, and experimentation without altering the original data.`
+
 		usage = "fork [id]"
 	)
 
@@ -38,16 +40,16 @@ func newFork() *cobra.Command {
 		flag.String{
 			Name:        "name",
 			Shorthand:   "n",
-			Description: "Name of the new volume",
+			Description: "The name of the new volume",
 		},
 		flag.Bool{
 			Name:        "machines-only",
-			Description: "volume will be visible to machines platform only",
+			Description: "volume will be visible to Machines platform only",
 			Hidden:      true,
 		},
 		flag.Bool{
 			Name:        "require-unique-zone",
-			Description: "Require volume to be placed in separate hardware zone from existing volumes",
+			Description: "Place the volume in a separate hardware zone from existing volumes. This is the default.",
 		},
 	)
 

internal/command/volumes/list.go

@@ -18,9 +18,9 @@ import (
 
 func newList() *cobra.Command {
 	const (
-		long = "List all the volumes associated with this application."
+		short = "List the volumes associated with an app."
 
-		short = "List the volumes for app"
+		long = short
 	)
 
 	cmd := command.New("list", short, long, runList,

internal/command/volumes/show.go

@@ -20,9 +20,9 @@ import (
 
 func newShow() (cmd *cobra.Command) {
 	const (
-		long = `Show details of an app's volume`
+		short = "Show the details of the specified volume."
 
-		short = "Show details of an app's volume"
+		long = short
 	)
 
 	cmd = command.New("show [id]", short, long, runShow,

internal/command/volumes/volumes.go

@@ -26,9 +26,9 @@ import (
 
 func New() *cobra.Command {
 	const (
-		long = "Commands for managing Fly Volumes associated with an application"
+		short = "Manage Fly Volumes."
 
-		short = "Volume management commands"
+		long = short
 
 		usage = "volumes <command>"
 	)