sigstore
Incomplete documentation for command arguments in code snippets
Description
Several code snippets in the Sigstore documentation fail to provide clear and concise descriptions of the arguments that a command uses. Instead, they rely on somewhat descriptive variable names, leaving the user to guess the intended purpose of the argument. This creates confusion and makes it difficult for users to understand how to use the command effectively. It would be beneficial to include complete documentation for each command's arguments, including their intended use and possible values, to improve the user experience and avoid potential errors.
For example in the Signing section in Cosign the following is given
$ cosign sign --key <key path>|<kms uri> [--payload <path>] [-a key=value] [--upload=true|false] [-f] [-r] <image uri>
When it could benefit from being re-written as:
$ cosign sign --key <key path>|<kms uri> [--payload <path>] [-a key=value] [--upload=true|false] [-f] [-r] <image uri>
Click here for an explanation of the arguments of the command above
The cosign sign command is used to sign container images. Here's a breakdown of the flags and options:
-
--key <key path>|<kms uri>: Specifies the location of the private key used for signing the image. It can be a path to a local file or a URI that points to a remote key management service. -
--payload <path>: Specifies the path to a file containing data that will be signed along with the image. This is optional. -
-a key=value: Adds an arbitrary key-value pair to the signature metadata. This can be used to include additional information about the image. -
--upload=true|false: Specifies whether to upload the signature to a transparency log. By default, this is set to true. -
-f: Overwrites an existing signature for the specified image. By default, the command will fail if a signature already exists. -
-r: Indicates that the image being signed is a root image. This flag is used for images that are the base layer of a Docker image. The last argument,<image uri>, is the URI of the container image that you want to sign.
The latter snippet provides a more inexperienced user with the option to get much needed clarification on the specific use the supplied arguments, while also not cluttering the page with details that a more experienced user would not be interested in.
@ltagliaferri can I take this up? If yes, would you please assign me this? 😃
I don't think we need a breakdown of every argument. Help text when running the CLI should be sufficient. It also keeps the source of truth with the CLI rather than having it duplicated here.
