Merge branch 'eread/create-help-text-style-guide' into 'master'

Create help text style guide for project

See merge request https://gitlab.com/gitlab-org/gitaly/-/merge_requests/5899

Merged-by: Andras Horvath <ahorvath@gitlab.com>
Approved-by: Russell Dickenson <rdickenson@gitlab.com>
Approved-by: Andras Horvath <ahorvath@gitlab.com>
Reviewed-by: Patrick Steinhardt <psteinhardt@gitlab.com>
Co-authored-by: Evan Read <eread@gitlab.com>

2 files changed, 64 insertions, 10 deletions

diff --git a/doc/configuration/README.md b/doc/configuration/README.md
index 877a4b9bd..1e6d89b47 100644
--- a/doc/configuration/README.md
+++ b/doc/configuration/README.md
@@ -160,18 +160,16 @@ pattern. All error messages are logged unconditionally.
 By default, health check gRPC messages are not logged. To enable them,
 set `GITALY_LOG_REQUEST_METHOD_ALLOW_PATTERN` to `.`.
 
-### Validation
+### Validate Gitaly configuration
 
-The `gitaly configuration validate` sub-command validates the provided configuration. Use `validate` before starting the service.
+To validate Gitaly configuration, use `gitaly configuration validate`. For example:
 
-`validate` prints all configuration problems to `STDOUT` in JSON format.
-The output's structure includes:
-
-- A key, which is the path to the configuration field where the problem is detected.
-- A message, with an explanation of the problem.
+```shell
+gitaly configuration validate < gitaly.config.toml
+```
 
-#### Usage
+For more information, run:
 
 ```shell
-gitaly configuration validate
-```
\ No newline at end of file
+gitaly configuration validate --help
+```
diff --git a/doc/help_text_style_guide.md b/doc/help_text_style_guide.md
new file mode 100644
index 000000000..4f4f764a8
--- /dev/null
+++ b/doc/help_text_style_guide.md
@@ -0,0 +1,56 @@
+# Help text style guide
+
+The command-line interface (CLI) tools `gitaly` and `praefect` are the primary interfaces to Gitaly and Gitaly Cluster.
+For this reason, it's important that help text is standardized and complete.
+
+The [`urfave/cli` library](https://cli.urfave.org) is used for CLI tooling in this project. It provides a number of
+options for developers to provide help text to users.
+
+## Rules for options
+
+To help users discover `gitaly` and `praefect` features through the CLI:
+
+- Always provide a value for the `Description` field key. This field key provides a lot of space to describe the command
+  or subcommand. At a minimum, provide a longer full sentence restatement of (but don't duplicate) the `Usage` field key
+  value.
+- Because of a [known issue](https://gitlab.com/gitlab-org/gitaly/-/issues/5350), always set the `HideHelpCommand`
+  field key to `true`. Setting this hides the `COMMANDS:` section of the help text,
+  which hides a generated list of available subcommands, if available.
+
+  Instead, list subcommands in the value of the `Description` field key. For example:
+
+  ```go
+  Description: "This is a long description of all the things example command can do.\n\n" +
+
+                "Provides the following subcommands:\n\n" +
+
+                "- subcommand1\n\n" +
+                "- subcommand2\n\n",
+  ```
+
+## Rules for command strings
+
+When adding or updating `gitaly` and `praefect` CLI tools, use the following guidance for values for the different field
+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"`                                       |
+| `Description` | No             | Yes        | `Description: "This is a long description of all the things example command can do."` |
+
+### Specific rules for `Description`
+
+When providing values for the `Description` key:
+
+- If referring to the subcommand itself, put the subcommand in backticks. For example:
+
+  ```plaintext
+  `subcommand` can be run at any time.
+  ```
+
+## Related topics
+
+- [Voice and tone](https://design.gitlab.com/content/voice-and-tone) from GitLab Design System.
+- [Language](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language) from GitLab
+  Documentation Style Guide.