Edit Praefect command usage strings

16 files changed, 71 insertions, 23 deletions

diff --git a/doc/help_text_style_guide.md b/doc/help_text_style_guide.md
index 4f4f764a8..f7e028961 100644
--- a/doc/help_text_style_guide.md
+++ b/doc/help_text_style_guide.md
@@ -36,17 +36,61 @@ keys for commands and subcommands:
 | Field key     | All lower case | Use period | Example key and value                                                                 |
 |:--------------|:---------------|:-----------|:--------------------------------------------------------------------------------------|
 | `Name`        | Yes            | No         | `Name: "example"`                                                                     |
-| `Usage`       | No             | No         | `Usage: "Short description of example command"`                                       |
+| `Usage`       | Yes            | No         | `Usage: "short description of example command"`                                       |
 | `Description` | No             | Yes        | `Description: "This is a long description of all the things example command can do."` |
 
+### Specific rules for `Usage`
+
+When providing values for the `Usage` field key:
+
+- Don't mention Gitaly or Praefect explicitly. We imply in the help text the tool we're referring to.
+
+  - Do:
+
+    ```plaintext
+    start the daemon
+    ```
+
+  - Don't:
+
+    ```plaintext
+    start the Gitaly daemon
+    ```
+
+- Always start with a verb and always write the string from the user's perspective, not the tool's perspective:
+
+  - Do:
+
+    ```plaintext
+    run the process
+    ```
+
+  - Don't:
+
+    ```plaintext
+    runs the process
+    ```
+
+  - Don't:
+
+    ```plaintext
+    the process runs
+    ```
+
 ### Specific rules for `Description`
 
-When providing values for the `Description` key:
+When providing values for the `Description` field key:
+
+- If referring to subcommands or flags, put the subcommand or flag in backticks. For example:
+
+  ```plaintext
+  `subcommand` can be run at any time with the `flag` flag.
+  ```
 
-- If referring to the subcommand itself, put the subcommand in backticks. For example:
+- Can mention Gitaly, Praefect, or Gitaly Cluster. For example:
 
   ```plaintext
-  `subcommand` can be run at any time.
+  Runs all of the processes for the Gitaly Cluster.
   ```
 
 ## Related topics
diff --git a/internal/cli/praefect/serve.go b/internal/cli/praefect/serve.go
index 7df3c786f..5904dc072 100644
--- a/internal/cli/praefect/serve.go
+++ b/internal/cli/praefect/serve.go
@@ -44,6 +44,7 @@ func newServeCommand() *cli.Command {
 	return &cli.Command{
 		Name:            "serve",
 		Usage:           "launch the server daemon",
+		Description:     "Launch the Praefect server daemon.",
 		Action:          serveAction,
 		HideHelpCommand: true,
 		Before: func(context *cli.Context) error {
diff --git a/internal/cli/praefect/subcmd_accept_dataloss.go b/internal/cli/praefect/subcmd_accept_dataloss.go
index 0df67f8b4..0911f309a 100644
--- a/internal/cli/praefect/subcmd_accept_dataloss.go
+++ b/internal/cli/praefect/subcmd_accept_dataloss.go
@@ -12,7 +12,7 @@ import (
 func newAcceptDatalossCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "accept-dataloss",
-		Usage: "allows for accepting data loss in a repository",
+		Usage: "accept data loss in a repository",
 		Description: `The subcommand "accept-dataloss" allows for accepting data loss in a repository to enable it for
 writing again. The current version of the repository on the authoritative storage is set to be
 the latest version and replications to other nodes are scheduled in order to bring them consistent
diff --git a/internal/cli/praefect/subcmd_check.go b/internal/cli/praefect/subcmd_check.go
index 8bf12562a..95e7a7b27 100644
--- a/internal/cli/praefect/subcmd_check.go
+++ b/internal/cli/praefect/subcmd_check.go
@@ -15,8 +15,8 @@ import (
 func newCheckCommand(checkFuncs []service.CheckFunc) *cli.Command {
 	return &cli.Command{
 		Name:            "check",
-		Usage:           "runs startup checks",
-		Description:     `This command runs startup checks for Praefect.`,
+		Usage:           "run startup checks",
+		Description:     "Run Praefect startup checks.",
 		HideHelpCommand: true,
 		Flags: []cli.Flag{
 			&cli.BoolFlag{
diff --git a/internal/cli/praefect/subcmd_configuration.go b/internal/cli/praefect/subcmd_configuration.go
index 1a767bd45..aaa53426b 100644
--- a/internal/cli/praefect/subcmd_configuration.go
+++ b/internal/cli/praefect/subcmd_configuration.go
@@ -7,7 +7,8 @@ const configurationCmdName = "configuration"
 func newConfigurationCommand() *cli.Command {
 	return &cli.Command{
 		Name:            configurationCmdName,
-		Usage:           "manages configuration",
+		Usage:           "manage configuration",
+		Description:     "Manage Praefect configuration.",
 		HideHelpCommand: true,
 		Subcommands: []*cli.Command{
 			newConfigurationValidateCommand(),
diff --git a/internal/cli/praefect/subcmd_dataloss.go b/internal/cli/praefect/subcmd_dataloss.go
index 87102dd1f..52ce4082b 100644
--- a/internal/cli/praefect/subcmd_dataloss.go
+++ b/internal/cli/praefect/subcmd_dataloss.go
@@ -14,7 +14,7 @@ import (
 func newDatalossCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "dataloss",
-		Usage: "identifies stale Gitaly nodes",
+		Usage: "identify stale nodes",
 		Description: "The subcommand \"dataloss\" identifies Gitaly nodes which are missing data from the\n" +
 			"previous write-enabled primary node. It does so by looking through incomplete\n" +
 			"replication jobs. This is useful for identifying potential data loss from a failover\n" +
diff --git a/internal/cli/praefect/subcmd_dial_nodes.go b/internal/cli/praefect/subcmd_dial_nodes.go
index 446d0aebc..d541060cb 100644
--- a/internal/cli/praefect/subcmd_dial_nodes.go
+++ b/internal/cli/praefect/subcmd_dial_nodes.go
@@ -11,7 +11,7 @@ import (
 func newDialNodesCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "dial-nodes",
-		Usage: "checks connection with remote nodes",
+		Usage: "check connection with remote nodes",
 		Description: "The subcommand \"dial-nodes\" helps diagnose connection problems to Gitaly or\n" +
 			"Praefect. The subcommand works by sourcing the connection information from\n" +
 			"the config file, and then dialing and health checking the remote nodes.",
diff --git a/internal/cli/praefect/subcmd_list_untracked_repositories.go b/internal/cli/praefect/subcmd_list_untracked_repositories.go
index 375f5c45d..a84ac43bc 100644
--- a/internal/cli/praefect/subcmd_list_untracked_repositories.go
+++ b/internal/cli/praefect/subcmd_list_untracked_repositories.go
@@ -22,7 +22,7 @@ import (
 func newListUntrackedRepositoriesCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "list-untracked-repositories",
-		Usage: "shows repositories not tracked by Praefect",
+		Usage: "list untracked repositories",
 		Description: "This command checks whether all repositories on all Gitaly nodes are tracked by Praefect.\n" +
 			"If a repository is found on the disk, but it is not known to Praefect, then the location of\n" +
 			"that repository will be written to the standard output stream in JSON format.\n" +
diff --git a/internal/cli/praefect/subcmd_metadata.go b/internal/cli/praefect/subcmd_metadata.go
index 30ef2d516..8f18d5fcf 100644
--- a/internal/cli/praefect/subcmd_metadata.go
+++ b/internal/cli/praefect/subcmd_metadata.go
@@ -12,7 +12,7 @@ import (
 func newMetadataCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "metadata",
-		Usage: "shows metadata information about repository",
+		Usage: "show metadata information about repository",
 		Description: "The command provides metadata information about the repository. It includes " +
 			"identifier of the repository, path on the disk for it and it's replicas, information " +
 			"about replicas such as if it is assigned or not, its generation, health state, the storage, " +
diff --git a/internal/cli/praefect/subcmd_remove_repository.go b/internal/cli/praefect/subcmd_remove_repository.go
index 54ce8d035..846a576ec 100644
--- a/internal/cli/praefect/subcmd_remove_repository.go
+++ b/internal/cli/praefect/subcmd_remove_repository.go
@@ -30,7 +30,7 @@ const (
 func newRemoveRepositoryCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "remove-repository",
-		Usage: "removes repository from the Gitaly cluster",
+		Usage: "remove a repository from the cluster",
 		Description: "This command removes all state associated with a given repository from the Gitaly Cluster.\n" +
 			"This includes both on-disk repositories on all relevant Gitaly nodes as well as any potential\n" +
 			"database state as tracked by Praefect, or optionally only database state.\n" +
diff --git a/internal/cli/praefect/subcmd_sql_migrate_down.go b/internal/cli/praefect/subcmd_sql_migrate_down.go
index 8a70e8c2e..9997ba202 100644
--- a/internal/cli/praefect/subcmd_sql_migrate_down.go
+++ b/internal/cli/praefect/subcmd_sql_migrate_down.go
@@ -14,7 +14,7 @@ const sqlMigrateDownCmdName = "sql-migrate-down"
 func newSQLMigrateDownCommand() *cli.Command {
 	return &cli.Command{
 		Name:  sqlMigrateDownCmdName,
-		Usage: "applies revert SQL migrations",
+		Usage: "apply revert SQL migrations",
 		Description: "The sql-migrate-down subcommand applies revert migrations to the configured database.\n" +
 			"It accepts a single argument - amount of migrations to revert.",
 		HideHelpCommand: true,
diff --git a/internal/cli/praefect/subcmd_sql_migrate_status.go b/internal/cli/praefect/subcmd_sql_migrate_status.go
index 08e4acfca..60dbf6343 100644
--- a/internal/cli/praefect/subcmd_sql_migrate_status.go
+++ b/internal/cli/praefect/subcmd_sql_migrate_status.go
@@ -14,7 +14,7 @@ const sqlMigrateStatusCmdName = "sql-migrate-status"
 func newSQLMigrateStatusCommand() *cli.Command {
 	return &cli.Command{
 		Name:  sqlMigrateStatusCmdName,
-		Usage: "shows applied database migrations",
+		Usage: "show applied database migrations",
 		Description: "The commands prints a table of the migration identifiers applied to the database\n" +
 			"with the timestamp for each when it was applied.",
 		HideHelpCommand: true,
diff --git a/internal/cli/praefect/subcmd_sql_ping.go b/internal/cli/praefect/subcmd_sql_ping.go
index 665d86d0a..1148f2c53 100644
--- a/internal/cli/praefect/subcmd_sql_ping.go
+++ b/internal/cli/praefect/subcmd_sql_ping.go
@@ -13,7 +13,7 @@ const sqlPingCmdName = "sql-ping"
 func newSQLPingCommand() *cli.Command {
 	return &cli.Command{
 		Name:            sqlPingCmdName,
-		Usage:           "checks reachability of the database",
+		Usage:           "check reachability of the database",
 		Description:     "The subcommand checks if the database configured in the configuration file is reachable",
 		HideHelpCommand: true,
 		Action:          sqlPingAction,
diff --git a/internal/cli/praefect/subcmd_track_repositories.go b/internal/cli/praefect/subcmd_track_repositories.go
index ea61ebe8a..daf55ca2c 100644
--- a/internal/cli/praefect/subcmd_track_repositories.go
+++ b/internal/cli/praefect/subcmd_track_repositories.go
@@ -22,7 +22,7 @@ const (
 func newTrackRepositoriesCommand() *cli.Command {
 	return &cli.Command{
 		Name:  trackRepositoriesCmdName,
-		Usage: "process bulk requests to track repositories in Praefect",
+		Usage: "process bulk requests to track repositories",
 		Description: "This command allows bulk requests for repositories to be tracked by Praefect.\n" +
 			"The -input-path flag must be the path of a file containing the details of the repositories\n" +
 			"to track as a list of newline-delimited JSON objects. Each line must contain the details for\n" +
diff --git a/internal/cli/praefect/subcmd_track_repository.go b/internal/cli/praefect/subcmd_track_repository.go
index 86e461406..10c50715c 100644
--- a/internal/cli/praefect/subcmd_track_repository.go
+++ b/internal/cli/praefect/subcmd_track_repository.go
@@ -31,7 +31,7 @@ const (
 func newTrackRepositoryCommand() *cli.Command {
 	return &cli.Command{
 		Name:  trackRepositoryCmdName,
-		Usage: "Praefect starts to track given repository",
+		Usage: "start tracking a repository",
 		Description: "This command adds a given repository to be tracked by Praefect.\n" +
 			"It checks if the repository exists on disk on the authoritative storage,\n" +
 			"and whether database records are absent from tracking the repository.\n" +
diff --git a/internal/cli/praefect/subcmd_verify.go b/internal/cli/praefect/subcmd_verify.go
index 5e40e8a91..fd4781e12 100644
--- a/internal/cli/praefect/subcmd_verify.go
+++ b/internal/cli/praefect/subcmd_verify.go
@@ -14,11 +14,13 @@ const verifyCmdName = "verify"
 func newVerifyCommand() *cli.Command {
 	return &cli.Command{
 		Name:  verifyCmdName,
-		Usage: "marks a discrete repository, or repositories of a storage, or repositories of a virtual storage to be verified",
-		Description: "The command marks a single repository if 'repository-id' flag is provided or a batch of\n" +
-			"repositories that belong to a particular storage or virtual storage to be checked they exist.\n" +
-			"The repository existence is confirmed if repository exists on the disk. That verification operation\n" +
-			"runs in background and executes verification asynchronously.",
+		Usage: "mark repositories for verification",
+		Description: "Mark for verification:\n\n" +
+
+			"- A single repository if the `repository-id` flag is provided.\n" +
+			"- A batch of repositories that belong to a particular storage or virtual storage if they exist on disk.\n\n" +
+
+			"Verification runs asynchronously in the background.",
 		HideHelpCommand: true,
 		Action:          verifyAction,
 		Flags: []cli.Flag{