doc: update per comments

Signed-off-by: Yi Zha <[email protected]>
notaryproject · Mar 16, 2023 · 5d789ab · 5d789ab
1 parent 77d0790
commit 5d789ab
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 34 deletions.
diff --git a/specs/commandline/policy.md b/specs/commandline/policy.md
@@ -2,9 +2,9 @@
 
 ## Description
 
-As part of signature verification workflow, users need to configure the trust policies to specify trusted identities that signed the artifacts, and the level of signature verification to use. For more details, see [trust policy specification and examples](https://github.com/notaryproject/notaryproject/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy).
+As part of signature verification workflow, users need to configure the trust policy configuration file to specify trusted identities that signed the artifacts, the level of signature verification to use and other settings. For more details, see [trust policy specification and examples](https://github.com/notaryproject/notaryproject/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy).
 
-The `notation policy` command provides a user-friendly way to manage trust policies. It allows users to import/export trust policies from/to a JSON file, and show trust policies. To get started user can use following sample trust policy. In this sample, there are four policies configured for different requirements:
+The `notation policy` command provides a user-friendly way to manage trust policies. It allows users to show trust policy configuration, import/export a trust policy configuration file from/to a JSON file. To get started user can refer to the following trust policy configuration sample. In this sample, there are four policies configured for different requirements:
 
 - The Policy named "wabbit-networks-images" is for verifying images signed by Wabbit Networks and stored in two repositories `registry.acme-rockets.io/software/net-monitor` and `registry.acme-rockets.io/software/net-logger`.
 - Policy named "unsigned-image" is for skipping the verification on unsigned images stored in repository `registry.acme-rockets.io/software/unsigned/net-utils`.
@@ -72,14 +72,14 @@ The `notation policy` command provides a user-friendly way to manage trust polic
 ### notation policy command
 
 ```text
-Manage trust policies for signature verification.
+Manage trust policy configuration for signature verification.
 
 Usage:
   notation policy [command]
 
 Available Commands:
-  import    import trust policies from a JSON file
-  show      show trust policies
+  import    import trust policy configuration from a JSON file
+  show      show trust policy configuration
 
 Flags:
   -h, --help   help for policy
@@ -88,22 +88,22 @@ Flags:
 ### notation policy import
 
 ```text
-Import trust policies from a JSON file
+Import trust policy configuration from a JSON file
 
 Usage:
   notation policy import [flags] <file_path>
 
 Flags:
   -d, --debug     debug mode
-      --force     override the existing trust policies, never prompt
+      --force     override the existing trust policy configuration, never prompt
   -h, --help      help for import
   -v, --verbose   verbose mode
 ```
 
 ### notation policy show
 
 ```text
-Show trust policies
+Show trust policy configuration
 
 Usage:
   notation policy show [flags]
@@ -116,48 +116,48 @@ Flags:
 
 ## Usage
 
-### Import trust policies from a JSON file
+### Import trust policy configuration from a JSON file
 
-An example of importing trust policies from a JSON file:
+An example of import trust policy configuration from a JSON file:
 
 ```shell  
 notation policy import ./my_policy.json
 ```
 
-The trust policies in the JSON file should be validated according to [trust policy properties](https://github.com/notaryproject/notaryproject/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy-properties). A successful message should be printed out if trust policies are imported successfully. Error logs including the reason should be printed out if the importing fails.
+The trust policy configuration in the JSON file should be validated according to [trust policy properties](https://github.com/notaryproject/notaryproject/blob/v1.0.0-rc.2/specs/trust-store-trust-policy.md#trust-policy-properties). A successful message should be printed out if trust policy configuration are imported successfully. Error logs including the reason should be printed out if the importing fails.
 
-Use `--force` flag to override existing policies without prompt.
+If there is an existing trust policy configuration, prompt for users to confirm whether discarding existing configuration or not. Users can use `--force` flag to discard existing trust policy configuration without prompt.
 
 ### Show trust policies
 
-Use the following command to show trust policies:
+Use the following command to show trust policy configuration:
 
 ```shell
 notation policy show
 ```
 
-Upon successful execution, the trust policies are printed out. If trust policies are not configured, users should receive an error message, and a tip to import trust policies from a JSON file.
+Upon successful execution, the trust policy configuration are printed out in a pretty JSON format. If trust policy is not configured, users should receive an error message, and a tip to import trust policy configuration from a JSON file.
 
-### Export trust policies into a JSON file
+### Export trust policy configuration into a JSON file
 
 Users can redirect the output of command `notation policy show` to a JSON file.
 
 ```shell
 notation policy show > ./trust_policy.json
 ```
 
-### Update trust policies
+### Update trust policy configuration
 
-The steps to update trust policies:
+The steps to update trust policy configuration:
 
-1. Export trust policies into a JSON file.
+1. Export trust policy configuration into a JSON file.
 
    ```shell
    notation policy show > ./trust_policy.json
    ```
 
-2. Edit the exported JSON file "trust_policy.json", update trust policies and save the file.
-3. Import trust policies from the file.
+2. Edit the exported JSON file "trust_policy.json", update trust policy configuration and save the file.
+3. Import trust policy configuration from the file.
 
    ```shell
    notation policy import ./trust_policy.json

diff --git a/specs/notation-cli.md b/specs/notation-cli.md
@@ -4,19 +4,19 @@ This spec contains reference information on using notation commands. Each comman
 
 ## Notation Commands
 
-| Command                                     | Description                                                |
-| ------------------------------------------- | ---------------------------------------------------------- |
-| [certificate](./commandline/certificate.md) | Manage certificates in trust store                         |
-| [inspect](./commandline/inspect.md)         | Inspect signatures                                         |
-| [key](./commandline/key.md)                 | Manage keys used for signing                               |
-| [list](./commandline/list.md)               | List signatures of the signed artifact                     |
-| [login](./commandline/login.md)             | Login to registries                                        |
-| [logout](./commandline/logout.md)           | Log out from the logged in registries                      |
-| [plugin](./commandline/plugin.md)           | Manage plugins                                             |
-| [policy](./commandline/policy.md)           | [Preview] Manage trust policies for signature verification |
-| [sign](./commandline/sign.md)               | Sign artifacts                                             |
-| [verify](./commandline/verify.md)           | Verify artifacts                                           |
-| [version](./commandline/version.md)         | Print the version of notation CLI                          |
+| Command                                     | Description                                                            |
+| ------------------------------------------- | ---------------------------------------------------------------------- |
+| [certificate](./commandline/certificate.md) | Manage certificates in trust store                                     |
+| [inspect](./commandline/inspect.md)         | Inspect signatures                                                     |
+| [key](./commandline/key.md)                 | Manage keys used for signing                                           |
+| [list](./commandline/list.md)               | List signatures of the signed artifact                                 |
+| [login](./commandline/login.md)             | Login to registries                                                    |
+| [logout](./commandline/logout.md)           | Log out from the logged in registries                                  |
+| [plugin](./commandline/plugin.md)           | Manage plugins                                                         |
+| [policy](./commandline/policy.md)           | [Preview] Manage trust policy configuration for signature verification |
+| [sign](./commandline/sign.md)               | Sign artifacts                                                         |
+| [verify](./commandline/verify.md)           | Verify artifacts                                                       |
+| [version](./commandline/version.md)         | Print the version of notation CLI                                      |
 
 ## Notation Outline
 
@@ -34,7 +34,7 @@ Available Commands:
   login       Login to registry
   logout      Log out from the logged in registries
   plugin      Manage plugins
-  policy      [Preview] Manage trust policies for signature verification
+  policy      [Preview] Manage trust policy configuration for signature verification
   sign        Sign artifacts
   verify      Verify artifacts
   version     Show the notation version information