diff --git a/src/lib_client_base/client_aliases.ml b/src/lib_client_base/client_aliases.ml
index 41351edc4..69216ae2f 100644
--- a/src/lib_client_base/client_aliases.ml
+++ b/src/lib_client_base/client_aliases.ml
@@ -75,6 +75,8 @@ module type Alias = sig
     ?desc:string ->
     ('a, (< .. > as 'obj), 'ret) Cli_entries.params ->
     (fresh_param -> 'a, 'obj, 'ret) Cli_entries.params
+  val force_switch :
+    (bool, Client_commands.full_context) arg
   val of_fresh :
     #Client_commands.wallet ->
     bool ->
@@ -225,9 +227,15 @@ module Alias = functor (Entity : Entity) -> struct
 
   let source_param ?(name = "src") ?(desc = "source " ^ Entity.name) next =
     let desc =
-      desc ^ "\n"
-      ^ "can be an alias, file or literal (autodetected in this order)\n\
-         use 'file:path', 'text:literal' or 'alias:name' to force" in
+      Format.asprintf
+        "%s\n\
+         Can be a %s name, a file or a raw %s literal. If the \
+         parameter is not the name of an existing %s, the client will \
+         look for a file containing a %s, and if it does not exist, \
+         the argument will be read as a raw %s.\n\
+         Use 'alias:name', 'file:path' or 'text:literal' to disable \
+         autodetect."
+        desc Entity.name Entity.name Entity.name Entity.name Entity.name in
     param ~name ~desc
       (parameter (fun cctxt s ->
            let read path =
@@ -264,6 +272,10 @@ module Alias = functor (Entity : Entity) -> struct
            end))
       next
 
+  let force_switch =
+    Client_commands.force_switch
+      ~doc:("overwrite existing " ^ Entity.name) ()
+
   let name (wallet : #wallet) d =
     rev_find wallet d >>=? function
     | None -> Entity.to_source wallet d
diff --git a/src/lib_client_base/client_aliases.mli b/src/lib_client_base/client_aliases.mli
index 943185fe6..18d5c4893 100644
--- a/src/lib_client_base/client_aliases.mli
+++ b/src/lib_client_base/client_aliases.mli
@@ -71,6 +71,8 @@ module type Alias = sig
     ?desc:string ->
     ('a, (< .. > as 'obj), 'ret) Cli_entries.params ->
     (fresh_param -> 'a, 'obj, 'ret) Cli_entries.params
+  val force_switch :
+    (bool, Client_commands.full_context) Cli_entries.arg
   val of_fresh :
     #Client_commands.wallet ->
     bool ->
diff --git a/src/lib_client_base/client_commands.ml b/src/lib_client_base/client_commands.ml
index 39d82b39a..d48facc3a 100644
--- a/src/lib_client_base/client_commands.ml
+++ b/src/lib_client_base/client_commands.ml
@@ -169,8 +169,5 @@ let commands_for_version version =
   try Protocol_hash.Table.find versions version
   with Not_found -> raise Version_not_found
 
-let force_switch =
-  Cli_entries.switch
-    ~parameter:"-force"
-    ~doc:"Take an action that will overwrite data.\
-          This silences any warnings and some checks"
+let force_switch ?(doc = "Silence any warnings and some checks.") () =
+  Cli_entries.switch ~parameter:"-force" ~doc
diff --git a/src/lib_client_base/client_commands.mli b/src/lib_client_base/client_commands.mli
index ead142c48..4b951a142 100644
--- a/src/lib_client_base/client_commands.mli
+++ b/src/lib_client_base/client_commands.mli
@@ -77,8 +77,8 @@ val commands_for_version: Protocol_hash.t -> command list
 val get_versions: unit -> (Protocol_hash.t * (command list)) list
 
 (** Have a command execute ignoring warnings.
-    This switch should be used when data will be overwritten. *)
-val force_switch : (bool, full_context) Cli_entries.arg
+    Default doc is ["Silence any warnings and some checks."]. *)
+val force_switch : ?doc:string -> unit -> (bool, full_context) Cli_entries.arg
 
 val default_base_dir : string
 val default_block : Block_services.block
diff --git a/src/lib_client_base/client_config.ml b/src/lib_client_base/client_config.ml
index a2a484fe3..17c53f099 100644
--- a/src/lib_client_base/client_config.ml
+++ b/src/lib_client_base/client_config.ml
@@ -146,49 +146,50 @@ let base_dir_arg =
   arg
     ~parameter:"-base-dir"
     ~placeholder:"path"
-    ~doc:("The directory where the Tezos client will store all its data. By default "
-          ^ Client_commands.default_base_dir)
+    ~doc:("client data directory\n\
+           The directory where the Tezos client will store all its data.\n\
+           By default " ^ Client_commands.default_base_dir)
     string_parameter
 let config_file_arg =
   arg
     ~parameter:"-config-file"
     ~placeholder:"path"
-    ~doc:"The main configuration file."
+    ~doc:"configuration file"
     string_parameter
 let timings_switch =
   switch
     ~parameter:"-timings"
-    ~doc:"Show RPC request times if present."
+    ~doc:"show RPC request times"
 let block_arg =
   default_arg
     ~parameter:"-block"
-    ~placeholder:"hash|head|head~n"
-    ~doc:"The block on which to apply contextual commands."
+    ~placeholder:"hash|tag"
+    ~doc:"block on which to apply contextual commands"
     ~default:(Block_services.to_string default_cli_args.block)
     block_parameter
 let protocol_arg =
   arg
     ~parameter:"-protocol"
     ~placeholder:"hash"
-    ~doc:"Use contextual commands of a specific protocol."
+    ~doc:"use commands of a specific protocol"
     protocol_parameter
 let log_requests_switch =
   switch
     ~parameter:"-log-requests"
-    ~doc:"Causes all requests and responses to the node to be logged."
+    ~doc:"log all requests to the node"
 
 (* Command-line args which can be set in config file as well *)
 let addr_arg =
   arg
     ~parameter:"-addr"
     ~placeholder:"IP addr|host"
-    ~doc:"The IP address of the node."
+    ~doc:"IP address of the node"
     string_parameter
 let port_arg =
   arg
     ~parameter:"-port"
     ~placeholder:"number"
-    ~doc:"The RPC port of the node."
+    ~doc:"RPC port of the node"
     (parameter
        (fun _ x -> try
            return (int_of_string x)
@@ -197,7 +198,7 @@ let port_arg =
 let tls_switch =
   switch
     ~parameter:"-tls"
-    ~doc:"Use TLS to connect to node."
+    ~doc:"use TLS to connect to node."
 
 let read_config_file config_file = match
     Utils.read_file ~bin:false config_file
@@ -205,7 +206,7 @@ let read_config_file config_file = match
   with
   | exception (Sys_error msg) ->
       failwith
-        "Error: can't read the configuration file: %s@,%s"
+        "Can't read the configuration file: %s@,%s"
         config_file msg
   | Error msg ->
       failwith
@@ -224,7 +225,7 @@ let commands config_file cfg =
   let open Cli_entries in
   let group = { Cli_entries.name = "config" ;
                 title = "Commands for editing and viewing the client's config file." } in
-  [ command ~group ~desc:"show the config file"
+  [ command ~group ~desc:"Show the config file."
       no_options
       (fixed [ "config" ; "show" ])
       (fun () (cctxt : Client_commands.full_context) ->
@@ -239,19 +240,34 @@ let commands config_file cfg =
            read_config_file config_file >>=? fun cfg ->
            cctxt#message "%a@," pp_cfg cfg >>= return) ;
 
-    command ~group ~desc:"reset the config file to the factory defaults"
+    command ~group ~desc:"Reset the config file to the factory defaults."
       no_options
       (fixed [ "config" ; "reset" ])
       (fun () _cctxt ->
          return Cfg_file.(write config_file default)) ;
 
-    command ~group ~desc:"update the config based on the current cli values"
+    command ~group
+      ~desc:"Update the config based on the current cli values.\n\
+             Loads the current configuration (default or as specified \
+             with `-config-file`), applies alterations from other \
+             command line arguments (such as the node's address, \
+             etc.), and overwrites the updated configuration file."
       no_options
       (fixed [ "config" ; "update" ])
       (fun () _cctxt ->
          return Cfg_file.(write config_file cfg)) ;
 
-    command ~group ~desc:"create a config file based on the current CLI values"
+    command ~group
+      ~desc:"Create a config file based on the current CLI values.\n\
+             If the `-file` option is not passed, this will initialize \
+             the default config file, based on default parameters, \
+             altered by other command line options (such as the node's \
+             address, etc.).\n\
+             Otherwise, it will create a new config file, based on the \
+             default parameters (or the the ones specified with \
+             `-config-file`), altered by other command line \
+             options.\n\
+             The command will always fail if the file already exists."
       (args1
          (default_arg
             ~parameter:"-file"
diff --git a/src/lib_client_base/client_generic_rpcs.ml b/src/lib_client_base/client_generic_rpcs.ml
index d6b01e072..fcdccbec8 100644
--- a/src/lib_client_base/client_generic_rpcs.ml
+++ b/src/lib_client_base/client_generic_rpcs.ml
@@ -425,7 +425,8 @@ let group =
 
 let commands = [
 
-  command ~desc: "list all understood protocol versions"
+  command
+    ~desc: "List the protocol versions that this client understands."
     no_options
     (fixed [ "list" ; "versions" ])
     (fun () (cctxt : Client_commands.full_context) ->
@@ -434,37 +435,50 @@ let commands = [
          (Client_commands.get_versions ()) >>= fun () ->
        return ()) ;
 
-  command ~group ~desc: "list available RPCs (low level command for advanced users)"
+  command ~group
+    ~desc: "List RPCs under a given URL prefix.\n\
+            Some parts of the RPC service hierarchy depend on parameters,\n\
+            they are marked by a suffix `<dynamic>`.\n\
+            You can list these sub-hierarchies by providing a concrete URL prefix \
+            whose arguments are set to a valid value."
+    no_options
+    (prefixes [ "rpc" ; "list" ] @@ string ~name:"url" ~desc: "the URL prefix" @@ stop)
+    (fun () -> list) ;
+
+  command ~group
+    ~desc: "Alias to `rpc list /`."
     no_options
     (prefixes [ "rpc" ; "list" ] @@ stop)
     (fun () -> (list "/"));
 
-  command ~group ~desc: "list available RPCs (low level command for advanced users)"
+  command ~group
+    ~desc: "Get the input and output JSON schemas of an RPC."
     no_options
-    (prefixes [ "rpc" ; "list" ] @@ string ~name:"url" ~desc: "the RPC's prefix to be described" @@ stop)
-    (fun () -> list) ;
-
-  command ~group ~desc: "get the input and output JSON schemas of an RPC"
-    no_options
-    (prefixes [ "rpc" ; "schema" ] @@ string ~name: "url" ~desc: "the RPC's URL" @@ stop)
+    (prefixes [ "rpc" ; "schema" ] @@ string ~name: "url" ~desc: "the RPC url" @@ stop)
     (fun () -> schema) ;
 
-  command ~group ~desc: "get the humanoid readable input and output formats of an RPC"
+  command ~group
+    ~desc: "Get the humanoid readable input and output formats of an RPC."
     no_options
-    (prefixes [ "rpc" ; "format" ] @@ string ~name: "url" ~desc: "the RPC's URL" @@ stop)
+    (prefixes [ "rpc" ; "format" ] @@ string ~name: "url" ~desc: "the RPC URL" @@ stop)
     (fun () -> format) ;
 
-  command ~group ~desc: "call an RPC (low level command for advanced users)"
+  command ~group
+    ~desc: "Call an RPC.\n\
+            If input data is needed, a text editor will be popped up."
     no_options
-    (prefixes [ "rpc" ; "call" ] @@ string ~name: "url" ~desc: "the RPC's URL" @@ stop)
+    (prefixes [ "rpc" ; "call" ] @@ string ~name: "url" ~desc: "the RPC URL" @@ stop)
     (fun () -> call) ;
 
-  command ~group ~desc: "call an RPC (low level command for advanced users)"
+  command ~group
+    ~desc: "Call an RPC providing input data via the command line."
     no_options
-    (prefixes [ "rpc" ; "call" ] @@ string ~name: "url" ~desc: "the RPC's URL"
+    (prefixes [ "rpc" ; "call" ] @@ string ~name: "url" ~desc: "the RPC URL"
      @@ prefix "with"
      @@ string ~name:"input"
-       ~desc:"the JSON input to the RPC or `file:FILENAME`, which is the path to a file containing the JSON"
+       ~desc:"the raw JSON input to the RPC\n\
+              For instance, use `{}` to send the empty document.\n\
+              Alternatively, use `file:path` to read the JSON data from a file."
      @@ stop)
     (fun () -> call_with_file_or_json)
 
diff --git a/src/lib_client_base/client_helpers.ml b/src/lib_client_base/client_helpers.ml
index 797f5dd53..a3326fc1e 100644
--- a/src/lib_client_base/client_helpers.ml
+++ b/src/lib_client_base/client_helpers.ml
@@ -14,15 +14,14 @@ let unique_switch =
 
 let commands () = Cli_entries.[
     command
-      ~desc: "Lookup for the possible completion of a \
-              given prefix of Base58Check-encoded hash. This actually \
-              works only for blocks, operations, public key and contract \
-              identifiers."
+      ~desc: "Autocomplete a prefix of Base58Check-encoded hash.\n\
+              This actually works only for blocks, operations, public \
+              key and contract identifiers."
       (args1 unique_switch)
       (prefixes [ "complete" ] @@
        string
          ~name: "prefix"
-         ~desc: "the prefix of the Base58Check-encoded hash to be completed" @@
+         ~desc: "the prefix of the hash to complete" @@
        stop)
       (fun unique prefix (cctxt : Client_commands.full_context) ->
          Client_node_rpcs.complete
diff --git a/src/lib_client_base/client_keys.ml b/src/lib_client_base/client_keys.ml
index 7397fce6a..6b14c6a5a 100644
--- a/src/lib_client_base/client_keys.ml
+++ b/src/lib_client_base/client_keys.ml
@@ -145,21 +145,23 @@ let alias_keys cctxt name =
         else find_key tl
   in find_key l
 
+let force_switch =
+  Client_commands.force_switch ~doc:"overwrite existing keys" ()
+
 let group =
   { Cli_entries.name = "keys" ;
-    title = "Commands for managing cryptographic keys" }
+    title = "Commands for managing the wallet of cryptographic keys" }
 
 let commands () =
   let open Cli_entries in
-  let open Client_commands in
   let show_private_switch =
     switch
       ~parameter:"-show-secret"
-      ~doc:"Show the private key" in
+      ~doc:"show the private key" in
   [
 
-    command ~group ~desc: "generate a pair of keys"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Generate a pair of keys."
+      (args1 Secret_key.force_switch)
       (prefixes [ "gen" ; "keys" ]
        @@ Secret_key.fresh_alias_param
        @@ stop)
@@ -168,17 +170,19 @@ let commands () =
          gen_keys ~force cctxt name) ;
 
     command ~group ~desc: "Generate keys including the given string"
-      (args2 (switch ~doc:"The key must begin with tz1[containing]" ~parameter:"-prefix") force_switch)
+      (args2
+         (switch ~doc:"the key must begin with tz1[word]" ~parameter:"-prefix")
+         force_switch)
       (prefixes [ "gen" ; "vanity" ; "keys" ]
        @@ Public_key_hash.fresh_alias_param
        @@ prefix "matching"
-       @@ (seq_of_param @@ string ~name:"strs" ~desc:"String key must contain"))
+       @@ (seq_of_param @@ string ~name:"words" ~desc:"string key must contain one of these words"))
       (fun (prefix, force) name containing cctxt ->
          Public_key_hash.of_fresh cctxt force name >>=? fun name ->
          gen_keys_containing ~force ~prefix ~containing ~name cctxt) ;
 
-    command ~group ~desc: "add a secret key to the wallet"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Add a secret key to the wallet."
+      (args1 Secret_key.force_switch)
       (prefixes [ "add" ; "secret" ; "key" ]
        @@ Secret_key.fresh_alias_param
        @@ Secret_key.source_param
@@ -200,8 +204,8 @@ let commands () =
                    please don't use -force" name) >>=? fun () ->
              Secret_key.add ~force cctxt name sk) ;
 
-    command ~group ~desc: "add a public key to the wallet"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Add a public key to the wallet."
+      (args1 Public_key.force_switch)
       (prefixes [ "add" ; "public" ; "key" ]
        @@ Public_key.fresh_alias_param
        @@ Public_key.source_param
@@ -212,8 +216,8 @@ let commands () =
            name (Ed25519.Public_key.hash key) >>=? fun () ->
          Public_key.add ~force cctxt name key) ;
 
-    command ~group ~desc: "add a public key to the wallet"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Add a public key to the wallet."
+      (args1 Public_key.force_switch)
       (prefixes [ "add" ; "identity" ]
        @@ Public_key_hash.fresh_alias_param
        @@ Public_key_hash.source_param
@@ -222,7 +226,7 @@ let commands () =
          Public_key_hash.of_fresh cctxt force name >>=? fun name ->
          Public_key_hash.add ~force cctxt name hash) ;
 
-    command ~group ~desc: "list all public key hashes and associated keys"
+    command ~group ~desc: "List all public key hashes and associated keys."
       no_options
       (fixed [ "list" ; "known" ; "identities" ])
       (fun () (cctxt : Client_commands.full_context) ->
@@ -236,7 +240,7 @@ let commands () =
               return ())
            l) ;
 
-    command ~group ~desc: "show the keys associated with an identity"
+    command ~group ~desc: "Show the keys associated with an identity."
       (args1 show_private_switch)
       (prefixes [ "show" ; "identity"]
        @@ Public_key_hash.alias_param
@@ -262,8 +266,8 @@ let commands () =
                        ok_lwt @@ cctxt#message "Secret Key: %s" priv
                  else return ()) ;
 
-    command ~group ~desc: "forget all keys"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Forget the entire wallet of keys."
+      (args1 (Client_commands.force_switch ~doc:"you got to use the force for that" ()))
       (fixed [ "forget" ; "all" ; "keys" ])
       (fun force cctxt ->
          fail_unless force
diff --git a/src/lib_client_base/client_keys.mli b/src/lib_client_base/client_keys.mli
index 5b68f470d..1c98d282a 100644
--- a/src/lib_client_base/client_keys.mli
+++ b/src/lib_client_base/client_keys.mli
@@ -32,4 +32,6 @@ val gen_keys:
   string ->
   unit tzresult Lwt.t
 
+val force_switch : (bool, Client_commands.full_context) Cli_entries.arg
+
 val commands: unit -> Client_commands.command list
diff --git a/src/lib_client_base/client_protocols.ml b/src/lib_client_base/client_protocols.ml
index be15fad6b..cfe4cb2ca 100644
--- a/src/lib_client_base/client_protocols.ml
+++ b/src/lib_client_base/client_protocols.ml
@@ -21,7 +21,7 @@ let commands () =
   let check_dir_parameter = parameter check_dir in
   [
 
-    command ~group ~desc: "list known protocols"
+    command ~group ~desc: "List protocols known by the node."
       no_options
       (prefixes [ "list" ; "protocols" ] stop)
       (fun () (cctxt : Client_commands.full_context) ->
@@ -30,7 +30,7 @@ let commands () =
          return ()
       );
 
-    command ~group ~desc: "inject a new protocol to the shell database"
+    command ~group ~desc: "Inject a new protocol into the node."
       no_options
       (prefixes [ "inject" ; "protocol" ]
        @@ param ~name:"dir" ~desc:"directory containing a protocol" check_dir_parameter
@@ -53,7 +53,7 @@ let commands () =
               return ())
       );
 
-    command ~group ~desc: "dump a protocol from the shell database"
+    command ~group ~desc: "Dump a protocol from the node's record of protocol."
       no_options
       (prefixes [ "dump" ; "protocol" ]
        @@ Protocol_hash.param ~name:"protocol hash" ~desc:""
diff --git a/src/lib_stdlib_lwt/cli_entries.ml b/src/lib_stdlib_lwt/cli_entries.ml
index d55912747..b1c0fad05 100644
--- a/src/lib_stdlib_lwt/cli_entries.ml
+++ b/src/lib_stdlib_lwt/cli_entries.ml
@@ -321,20 +321,23 @@ let search_command keyword (Command { params }) =
 let rec help_commands commands =
   [ command
       ~group:help_group
-      ~desc:"Print documentation of commands. \
-             Add search keywords to narrow list. \
+      ~desc:"Print documentation of commands.\n\
+             Add search keywords to narrow list.\n\
              Will display only the commands by default, \
              unless [-verbose] is passed or the list \
              of matching commands if less than 3."
       (args3
          (switch
-            ~doc:"Print terse output, regardless of number of commands returned"
+            ~doc:"Always print terse output.\n\
+                  Only shows command mnemonics, without documentation.\n\
+                  Disables automatic verbosity wrt. number of commands shown."
             ~parameter:"-terse")
          (switch
-            ~doc:"Print detailed output, regardless of number of commands returned"
+            ~doc:"Print detailed output.\n\
+                  Disables automatic verbosity wrt. number of commands shown."
             ~parameter:"-verbose")
          (default_arg
-            ~doc:"Select the manual's output format"
+            ~doc:"Select the manual's output format."
             ~placeholder: "plain|colors"
             ~parameter: "-format"
             ~default: (if Unix.isatty Unix.stdout then "colors" else "plain")
@@ -344,7 +347,10 @@ let rec help_commands commands =
                   | "colors" -> return `Ansi
                   | "plain" -> return `Plain
                   | _ -> failwith "Unknown manual format"))))
-      (prefix "man" @@ seq_of_param (string ~name:"keyword" ~desc:"Keyword to search for"))
+      (prefix "man"
+         (seq_of_param (string ~name:"keyword"
+                          ~desc:"Keyword to search for.\n\
+                                 If several are given they must all appear in the command.")))
       (fun (terse, details, format) keywords _ ->
          if terse && details
          then fail (Invalid_options_combination "Cannot specify both -verbose and -terse.")
@@ -531,13 +537,15 @@ let print_options_detailed (type ctx) =
   let help_option : type a.Format.formatter -> (a, ctx) arg -> unit =
     fun ppf -> function
       | Arg { parameter ; placeholder ; doc } ->
-          Format.fprintf ppf "@[<v 2>@{<opt>%s <%s>@}:@,@[<hov 0>%a@]@]"
+          Format.fprintf ppf "@[<hov 2>@{<opt>%s <%s>@}: %a@]"
             parameter placeholder Format.pp_print_text doc
       | DefArg { parameter ; placeholder ; doc ; default } ->
-          Format.fprintf ppf "@[<v 2>@{<opt>%s <%s>@} (default %s):@,@[<hov 0>%a@]@]"
-            parameter placeholder default Format.pp_print_text doc
+          Format.fprintf ppf "@[<hov 2>@{<opt>%s <%s>@}: %a@]"
+            parameter placeholder
+            Format.pp_print_text
+            (Format.asprintf "%s\nDefaults to `%s`." doc default)
       | Switch { parameter ; doc } ->
-          Format.fprintf ppf "@[<v 2>@{<opt>%s@}:@,@[<hov 0>%a@]@]"
+          Format.fprintf ppf "@[<hov 2>@{<opt>%s@}: %a@]"
             parameter Format.pp_print_text doc
   in let rec help : type b. Format.formatter -> (b, ctx) args -> unit =
        fun ppf -> function
@@ -616,7 +624,7 @@ let rec print_params_detailed
   = fun spec ppf -> function
     | Stop -> print_options_detailed ppf spec
     | Seq (n, desc, _) ->
-        Format.fprintf ppf "@[<v 2>@{<arg>%s@}:@,@[<hov 0>%a@]@]"
+        Format.fprintf ppf "@[<hov 2>@{<arg>%s@}: %a@]"
           n Format.pp_print_text (trim desc) ;
         begin match spec with
           | NoArgs -> ()
@@ -625,14 +633,14 @@ let rec print_params_detailed
     | Prefix (_, next) ->
         print_params_detailed spec ppf next
     | Param (n, desc, _, Stop) ->
-        Format.fprintf ppf "@[<v 2>@{<arg>%s@}:@,@[<hov 0>%a@]@]"
+        Format.fprintf ppf "@[<hov 2>@{<arg>%s@}: %a@]"
           n Format.pp_print_text (trim desc);
         begin match spec with
           | NoArgs -> ()
           | _ -> Format.fprintf ppf "@,%a" print_options_detailed spec
         end
     | Param (n, desc, _, next) ->
-        Format.fprintf ppf "@[<v 2>@{<arg>%s@}:@,@[<hov 0>%a@]@]@,%a"
+        Format.fprintf ppf "@[<hov 2>@{<arg>%s@}: %a@]@,%a"
           n Format.pp_print_text (trim desc) (print_params_detailed spec) next
 
 let contains_params_args :
diff --git a/src/proto_alpha/lib_client/client_baking_main.ml b/src/proto_alpha/lib_client/client_baking_main.ml
index 53cec7762..e1278ceb8 100644
--- a/src/proto_alpha/lib_client/client_baking_main.ml
+++ b/src/proto_alpha/lib_client/client_baking_main.ml
@@ -28,7 +28,7 @@ let commands () =
            then (true, true, true)
            else (endorsement, baking, denunciation) in
          run_daemon cctxt ?max_priority ~endorsement_delay ~endorsement ~baking ~denunciation delegates) ;
-    command ~group ~desc: "Forge and inject an endorsement operation"
+    command ~group ~desc: "Forge and inject an endorsement operation."
       (args1 max_priority_arg)
       (prefixes [ "endorse"; "for" ]
        @@ Client_keys.Public_key_hash.alias_param
@@ -36,7 +36,7 @@ let commands () =
        @@ stop)
       (fun max_priority (_, delegate) cctxt ->
          endorse_block cctxt ?max_priority delegate) ;
-    command ~group ~desc: "Forge and inject block using the delegate rights"
+    command ~group ~desc: "Forge and inject block using the delegate rights."
       (args3 max_priority_arg force_switch free_baking_switch)
       (prefixes [ "bake"; "for" ]
        @@ Client_keys.Public_key_hash.alias_param
@@ -45,13 +45,13 @@ let commands () =
       (fun (max_priority, force, free_baking) (_, delegate) cctxt ->
          bake_block cctxt cctxt#block
            ~force ?max_priority ~free_baking delegate) ;
-    command ~group ~desc: "Forge and inject a seed-nonce revelation operation"
+    command ~group ~desc: "Forge and inject a seed-nonce revelation operation."
       no_options
       (prefixes [ "reveal"; "nonce"; "for" ]
        @@ seq_of_param Block_hash.param)
       (fun () block_hashes cctxt ->
          reveal_block_nonces cctxt block_hashes) ;
-    command ~group ~desc: "Forge and inject redemption operations"
+    command ~group ~desc: "Forge and inject redemption operations."
       no_options
       (prefixes [ "reveal"; "nonces" ]
        @@ stop)
diff --git a/src/proto_alpha/lib_client/client_proto_args.ml b/src/proto_alpha/lib_client/client_proto_args.ml
index bc5c38199..60fd49fd1 100644
--- a/src/proto_alpha/lib_client/client_proto_args.ml
+++ b/src/proto_alpha/lib_client/client_proto_args.ml
@@ -62,7 +62,7 @@ let init_arg =
   default_arg
     ~parameter:"-init"
     ~placeholder:"data"
-    ~doc:"The initial value of the contract's storage."
+    ~doc:"initial value of the contract's storage"
     ~default:"Unit"
     string_parameter
 
@@ -70,7 +70,7 @@ let arg_arg =
   default_arg
     ~parameter:"-arg"
     ~placeholder:"data"
-    ~doc:"The argument passed to the contract's script, if needed."
+    ~doc:"argument passed to the contract's script, if needed"
     ~default:"Unit"
     string_parameter
 
@@ -78,7 +78,7 @@ let delegate_arg =
   arg
     ~parameter:"-delegate"
     ~placeholder:"identity"
-    ~doc:"Set the delegate of the contract.\
+    ~doc:"delegate of the contract\n\
           Must be a known identity."
     string_parameter
 
@@ -86,28 +86,33 @@ let source_arg =
   arg
     ~parameter:"-source"
     ~placeholder:"identity"
-    ~doc:"Set the source of the bonds to be paid.\
+    ~doc:"source of the bonds to be paid\n\
           Must be a known identity."
     string_parameter
 
 let spendable_switch =
   switch
     ~parameter:"-spendable"
-    ~doc:"Set the created contract to be spendable"
+    ~doc:"allow the manager to spend the contract's tokens"
 
 let force_switch =
   switch
     ~parameter:"-force"
-    ~doc:"Force the injection of branch-invalid operation or force \
+    ~doc:"disables the node's injection checks\n\
+          Force the injection of branch-invalid operation or force \
          \ the injection of block without a fitness greater than the \
          \ current head."
 
 let delegatable_switch =
   switch
     ~parameter:"-delegatable"
-    ~doc:"Set the created contract to be delegatable"
+    ~doc:"allow future delegate change"
 
-let tez_format = "text format: D,DDD,DDD.DDD,DDD (centiles are optional, commas are optional)"
+let tez_format =
+  "Text format: `D,DDD,DDD.DDD,DDD`.\n\
+   Tez and mutez and separated by a period sign. Trailing and pending \
+   zeroes are allowed. Commas are optional, but if present they must \
+   be placed every 3 digits."
 
 let tez_parameter param =
   parameter
@@ -130,13 +135,13 @@ let fee_arg =
   tez_arg
     ~default:"0.05"
     ~parameter:"-fee"
-    ~doc:"The fee in \xEA\x9C\xA9 to pay to the baker."
+    ~doc:"fee in \xEA\x9C\xA9 to pay to the baker"
 
 let max_priority_arg =
   arg
     ~parameter:"-max-priority"
-    ~placeholder:"prio"
-    ~doc:"Set the max_priority used when looking for baking slot."
+    ~placeholder:"slot"
+    ~doc:"maximum allowed baking slot"
     (parameter (fun _ s ->
          try return (int_of_string s)
          with _ -> fail (Bad_max_priority s)))
@@ -144,13 +149,15 @@ let max_priority_arg =
 let free_baking_switch =
   switch
     ~parameter:"-free-baking"
-    ~doc:"Only consider free baking slots."
+    ~doc:"only consider free baking slots"
 
 let endorsement_delay_arg =
   default_arg
     ~parameter:"-endorsement-delay"
     ~placeholder:"seconds"
-    ~doc:"Set the delay used before to endorse the current block."
+    ~doc:"delay before endorsing blocks\n\
+          Delay between notifications of new blocks from the node and \
+          production of endorsements for these blocks."
     ~default:"15"
     (parameter (fun _ s ->
          try return (int_of_string s)
@@ -159,20 +166,22 @@ let endorsement_delay_arg =
 let no_print_source_flag =
   switch
     ~parameter:"-no-print-source"
-    ~doc:"Don't print the source code if an error is encountered.\
-          This should be enabled for extremely large programs"
+    ~doc:"don't print the source code\n\
+          If an error is encountered, the client will print the \
+          contract's source code by default.\n\
+          This option disables this behaviour."
 
 module Daemon = struct
   let baking_switch =
     switch
       ~parameter:"-baking"
-      ~doc:"Run the baking daemon"
+      ~doc:"run the baking daemon"
   let endorsement_switch =
     switch
       ~parameter:"-endorsement"
-      ~doc:"Run the endorsement daemon"
+      ~doc:"run the endorsement daemon"
   let denunciation_switch =
     switch
       ~parameter:"-denunciation"
-      ~doc:"Run the denunciation daemon"
+      ~doc:"run the denunciation daemon"
 end
diff --git a/src/proto_alpha/lib_client/client_proto_context_commands.ml b/src/proto_alpha/lib_client/client_proto_context_commands.ml
index c2e2a849c..dd941467c 100644
--- a/src/proto_alpha/lib_client/client_proto_context_commands.ml
+++ b/src/proto_alpha/lib_client/client_proto_context_commands.ml
@@ -37,11 +37,14 @@ let group =
   { Cli_entries.name = "context" ;
     title = "Block contextual commands (see option -block)" }
 
+let alphanet =
+  { Cli_entries.name = "alphanet" ;
+    title = "Alphanet only commands" }
+
 let commands () =
   let open Cli_entries in
-  let open Client_commands in
   [
-    command ~group ~desc: "access the timestamp of the block"
+    command ~group ~desc: "Access the timestamp of the block."
       no_options
       (fixed [ "get" ; "timestamp" ])
       begin fun () (cctxt : Client_commands.full_context) ->
@@ -51,7 +54,7 @@ let commands () =
         return ()
       end ;
 
-    command ~group ~desc: "lists all non empty contracts of the block"
+    command ~group ~desc: "Lists all non empty contracts of the block."
       no_options
       (fixed [ "list" ; "contracts" ])
       begin fun () (cctxt : Client_commands.full_context) ->
@@ -62,7 +65,7 @@ let commands () =
         return ()
       end ;
 
-    command ~group ~desc: "get the balance of a contract"
+    command ~group ~desc: "Get the balance of a contract."
       no_options
       (prefixes [ "get" ; "balance" ; "for" ]
        @@ ContractAlias.destination_param ~name:"src" ~desc:"source contract"
@@ -73,7 +76,7 @@ let commands () =
         return ()
       end ;
 
-    command ~group ~desc: "get the storage of a contract"
+    command ~group ~desc: "Get the storage of a contract."
       no_options
       (prefixes [ "get" ; "storage" ; "for" ]
        @@ ContractAlias.destination_param ~name:"src" ~desc:"source contract"
@@ -87,7 +90,7 @@ let commands () =
             return ()
       end ;
 
-    command ~group ~desc: "get the manager of a contract"
+    command ~group ~desc: "Get the manager of a contract."
       no_options
       (prefixes [ "get" ; "manager" ; "for" ]
        @@ ContractAlias.destination_param ~name:"src" ~desc:"source contract"
@@ -102,7 +105,7 @@ let commands () =
         return ()
       end ;
 
-    command ~group ~desc: "get the delegate of a contract"
+    command ~group ~desc: "Get the delegate of a contract."
       no_options
       (prefixes [ "get" ; "delegate" ; "for" ]
        @@ ContractAlias.destination_param ~name:"src" ~desc:"source contract"
@@ -117,13 +120,13 @@ let commands () =
         return ()
       end ;
 
-    command ~group ~desc: "set the delegate of a contract"
+    command ~group ~desc: "Set the delegate of a contract."
       (args1 fee_arg)
       (prefixes [ "set" ; "delegate" ; "for" ]
        @@ ContractAlias.destination_param ~name:"src" ~desc:"source contract"
        @@ prefix "to"
        @@ Public_key_hash.alias_param
-         ~name: "mgr" ~desc: "New delegate of the contract"
+         ~name: "mgr" ~desc: "new delegate of the contract"
        @@ stop)
       begin fun fee (_, contract) (_, delegate) cctxt ->
         source_to_keys cctxt cctxt#block contract >>=? fun (src_pk, manager_sk) ->
@@ -131,8 +134,8 @@ let commands () =
         operation_submitted_message cctxt oph
       end ;
 
-    command ~group ~desc:"open a new account"
-      (args4 fee_arg delegate_arg delegatable_switch force_switch)
+    command ~group ~desc:"Open a new account."
+      (args4 fee_arg delegate_arg delegatable_switch Client_keys.force_switch)
       (prefixes [ "originate" ; "account" ]
        @@ RawContractAlias.fresh_alias_param
          ~name: "new" ~desc: "name of the new contract"
@@ -167,9 +170,9 @@ let commands () =
         operation_submitted_message ~contracts:[ contract ] cctxt oph
       end ;
 
-    command ~group ~desc: "Launch a smart contract on the blockchain"
+    command ~group ~desc: "Launch a smart contract on the blockchain."
       (args7
-         fee_arg delegate_arg force_switch
+         fee_arg delegate_arg Client_keys.force_switch
          delegatable_switch spendable_switch init_arg no_print_source_flag)
       (prefixes [ "originate" ; "contract" ]
        @@ RawContractAlias.fresh_alias_param
@@ -186,7 +189,7 @@ let commands () =
        @@ prefix "running"
        @@ Program.source_param
          ~name:"prg" ~desc: "script of the account\n\
-                             combine with -init if the storage type is not unit"
+                             Combine with -init if the storage type is not unit."
        @@ stop)
       begin fun (fee, delegate, force, delegatable, spendable, initial_storage, no_print_source)
         alias_name (_, manager) balance (_, source) program (cctxt : Client_commands.full_context) ->
@@ -204,24 +207,7 @@ let commands () =
               ~contracts:[contract] oph
       end ;
 
-    command ~group ~desc: "open a new (free) account"
-      (args1 force_switch)
-      (prefixes [ "originate" ; "free" ; "account" ]
-       @@ RawContractAlias.fresh_alias_param
-         ~name: "new" ~desc: "name of the new contract"
-       @@ prefix "for"
-       @@ Public_key_hash.alias_param
-         ~name: "mgr" ~desc: "manager of the new contract"
-       @@ stop)
-      begin fun force alias_name (_, manager_pkh) cctxt ->
-        RawContractAlias.of_fresh cctxt force alias_name >>=? fun alias_name ->
-        faucet ~manager_pkh cctxt#block cctxt () >>=? fun (oph, contract) ->
-        operation_submitted_message cctxt
-          ~contracts:[contract] oph >>=? fun () ->
-        save_contract ~force cctxt alias_name contract
-      end;
-
-    command ~group ~desc: "transfer tokens"
+    command ~group ~desc: "Transfer tokens / call a smart contract."
       (args3 fee_arg arg_arg no_print_source_flag)
       (prefixes [ "transfer" ]
        @@ tez_param
@@ -243,14 +229,31 @@ let commands () =
             operation_submitted_message cctxt ~contracts oph
       end;
 
-    command ~desc: "Activate a protocol"
+    command ~group:alphanet ~desc: "Open a new FREE account (Alphanet only)."
+      (args1 force_switch)
+      (prefixes [ "originate" ; "free" ; "account" ]
+       @@ RawContractAlias.fresh_alias_param
+         ~name: "new" ~desc: "name of the new contract"
+       @@ prefix "for"
+       @@ Public_key_hash.alias_param
+         ~name: "mgr" ~desc: "manager of the new contract"
+       @@ stop)
+      begin fun force alias_name (_, manager_pkh) cctxt ->
+        RawContractAlias.of_fresh cctxt force alias_name >>=? fun alias_name ->
+        faucet ~manager_pkh cctxt#block cctxt () >>=? fun (oph, contract) ->
+        operation_submitted_message cctxt
+          ~contracts:[contract] oph >>=? fun () ->
+        save_contract ~force cctxt alias_name contract
+      end;
+
+    command ~group:alphanet ~desc: "Activate a protocol (Alphanet dictator only)."
       no_options
       (prefixes [ "activate" ; "protocol" ]
        @@ Protocol_hash.param ~name:"version"
-         ~desc:"Protocol version (b58check)"
+         ~desc:"protocol version (b58check)"
        @@ prefixes [ "with" ; "key" ]
        @@ Environment.Ed25519.Secret_key.param
-         ~name:"password" ~desc:"Dictator's key"
+         ~name:"password" ~desc:"dictator's key"
        @@ stop)
       begin fun () hash seckey cctxt ->
         dictate cctxt cctxt#block
@@ -258,14 +261,14 @@ let commands () =
         operation_submitted_message cctxt oph
       end ;
 
-    command ~desc: "Fork a test protocol"
+    command ~group:alphanet ~desc: "Fork a test protocol (Alphanet dictator only)."
       no_options
       (prefixes [ "fork" ; "test" ; "protocol" ]
        @@ Protocol_hash.param ~name:"version"
-         ~desc:"Protocol version (b58check)"
+         ~desc:"protocol version (b58check)"
        @@ prefixes [ "with" ; "key" ]
        @@ Environment.Ed25519.Secret_key.param
-         ~name:"password" ~desc:"Dictator's key"
+         ~name:"password" ~desc:"dictator's key"
        @@ stop)
       begin fun () hash seckey cctxt ->
         dictate cctxt cctxt#block
diff --git a/src/proto_alpha/lib_client/client_proto_contracts.ml b/src/proto_alpha/lib_client/client_proto_contracts.ml
index c509982ed..6110d0ae9 100644
--- a/src/proto_alpha/lib_client/client_proto_contracts.ml
+++ b/src/proto_alpha/lib_client/client_proto_contracts.ml
@@ -64,8 +64,8 @@ module ContractAlias = struct
   let alias_param ?(name = "name") ?(desc = "existing contract alias") next =
     let desc =
       desc ^ "\n"
-      ^ "can be a contract alias or a key alias (autodetected in this order)\n\
-         use 'key:name' to force the later" in
+      ^ "Can be a contract alias or a key alias (autodetected in order).\n\
+         Use 'key:name' to force the later." in
     Cli_entries.(
       param ~name ~desc
         (parameter ~autocomplete:autocomplete
@@ -75,8 +75,8 @@ module ContractAlias = struct
   let destination_param ?(name = "dst") ?(desc = "destination contract") next =
     let desc =
       desc ^ "\n"
-      ^ "can be an alias, a key alias, or a literal (autodetected in this order)\n\
-         use 'text:literal', 'alias:name', 'key:name' to force" in
+      ^ "Can be an alias, a key, or a literal (autodetected in order).\n\
+         Use 'text:literal', 'alias:name', 'key:name' to force." in
     Cli_entries.(
       param ~name ~desc
         (parameter
diff --git a/src/proto_alpha/lib_client/client_proto_contracts_commands.ml b/src/proto_alpha/lib_client/client_proto_contracts_commands.ml
index 021b9cb6f..416f3636a 100644
--- a/src/proto_alpha/lib_client/client_proto_contracts_commands.ml
+++ b/src/proto_alpha/lib_client/client_proto_contracts_commands.ml
@@ -19,8 +19,8 @@ let commands  () =
   let open Cli_entries in
   [
 
-    command ~group ~desc: "add a contract to the wallet"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Add a contract to the wallet."
+      (args1 RawContractAlias.force_switch)
       (prefixes [ "remember" ; "contract" ]
        @@ RawContractAlias.fresh_alias_param
        @@ RawContractAlias.source_param
@@ -29,7 +29,7 @@ let commands  () =
          RawContractAlias.of_fresh cctxt force name >>=? fun name ->
          RawContractAlias.add ~force cctxt name hash) ;
 
-    command ~group ~desc: "remove a contract from the wallet"
+    command ~group ~desc: "Remove a contract from the wallet."
       no_options
       (prefixes [ "forget" ; "contract" ]
        @@ RawContractAlias.alias_param
@@ -37,7 +37,7 @@ let commands  () =
       (fun () (name, _) cctxt ->
          RawContractAlias.del cctxt name) ;
 
-    command ~group ~desc: "lists all known contracts"
+    command ~group ~desc: "Lists all known contracts in the wallet."
       no_options
       (fixed [ "list" ; "known" ; "contracts" ])
       (fun () (cctxt : Client_commands.full_context) ->
@@ -48,8 +48,8 @@ let commands  () =
                 (Contract.to_b58check contract) >>= return)
            contracts) ;
 
-    command ~group ~desc: "forget all known contracts"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Forget the entire wallet of known contracts."
+      (args1 RawContractAlias.force_switch)
       (fixed [ "forget" ; "all" ; "contracts" ])
       (fun force cctxt ->
          fail_unless
@@ -57,7 +57,7 @@ let commands  () =
            (failure "this can only used with option -force") >>=? fun () ->
          RawContractAlias.set cctxt []) ;
 
-    command ~group ~desc: "display a contract from the wallet"
+    command ~group ~desc: "Display a contract from the wallet."
       no_options
       (prefixes [ "show" ; "known" ; "contract" ]
        @@ RawContractAlias.alias_param
@@ -66,7 +66,7 @@ let commands  () =
          cctxt#message "%a\n%!" Contract.pp contract >>= fun () ->
          return ()) ;
 
-    command ~group ~desc: "tag a contract in the wallet"
+    command ~group ~desc: "Tag a contract in the wallet."
       no_options
       (prefixes [ "tag" ; "contract" ]
        @@ RawContractAlias.alias_param
@@ -81,7 +81,7 @@ let commands  () =
            | Some tags -> List.merge2 tags new_tags in
          Contract_tags.update cctxt alias new_tags) ;
 
-    command ~group ~desc: "remove tag(s) from a contract in the wallet"
+    command ~group ~desc: "Remove tag(s) from a contract in the wallet."
       no_options
       (prefixes [ "untag" ; "contract" ]
        @@ RawContractAlias.alias_param
diff --git a/src/proto_alpha/lib_client/client_proto_programs_commands.ml b/src/proto_alpha/lib_client/client_proto_programs_commands.ml
index a7ffbb383..13065a4c7 100644
--- a/src/proto_alpha/lib_client/client_proto_programs_commands.ml
+++ b/src/proto_alpha/lib_client/client_proto_programs_commands.ml
@@ -9,7 +9,7 @@
 
 let group =
   { Cli_entries.name = "programs" ;
-    title = "Commands for managing the record of known programs" }
+    title = "Commands for managing the library of known programs" }
 
 open Tezos_micheline
 open Client_proto_programs
@@ -20,19 +20,19 @@ let commands () =
   let show_types_switch =
     switch
       ~parameter:"-details"
-      ~doc:"Show the types of each instruction" in
+      ~doc:"show the types of each instruction" in
   let emacs_mode_switch =
     switch
       ~parameter:"-emacs"
-      ~doc:"Output in michelson-mode.el compatible format" in
+      ~doc:"output in `michelson-mode.el` compatible format" in
   let trace_stack_switch =
     switch
       ~parameter:"-trace-stack"
-      ~doc:"Show the stack after each step" in
+      ~doc:"show the stack after each step" in
   let amount_arg =
     Client_proto_args.tez_arg
       ~parameter:"-amount"
-      ~doc:"The amount of the transfer in \xEA\x9C\xA9."
+      ~doc:"amount of the transfer in \xEA\x9C\xA9"
       ~default:"0.05" in
   let data_parameter =
     Cli_entries.parameter (fun _ data ->
@@ -40,7 +40,7 @@ let commands () =
                     @@ Michelson_v1_parser.parse_expression data)) in
   [
 
-    command ~group ~desc: "lists all known programs"
+    command ~group ~desc: "Lists all programs in the library."
       no_options
       (fixed [ "list" ; "known" ; "programs" ])
       (fun () (cctxt : Client_commands.full_context) ->
@@ -48,8 +48,8 @@ let commands () =
          Lwt_list.iter_s (fun (n, _) -> cctxt#message "%s" n) list >>= fun () ->
          return ()) ;
 
-    command ~group ~desc: "remember a program under some name"
-      (args1 Client_commands.force_switch)
+    command ~group ~desc: "Add a program to the library."
+      (args1 Program.force_switch)
       (prefixes [ "remember" ; "program" ]
        @@ Program.fresh_alias_param
        @@ Program.source_param
@@ -58,14 +58,14 @@ let commands () =
          Program.of_fresh cctxt force name >>=? fun name ->
          Program.add ~force cctxt name hash) ;
 
-    command ~group ~desc: "forget a remembered program"
+    command ~group ~desc: "Remove a program from the library."
       no_options
       (prefixes [ "forget" ; "program" ]
        @@ Program.alias_param
        @@ stop)
       (fun () (name, _) cctxt -> Program.del cctxt name) ;
 
-    command ~group ~desc: "display a program"
+    command ~group ~desc: "Display a program from the library."
       no_options
       (prefixes [ "show" ; "known" ; "program" ]
        @@ Program.alias_param
@@ -75,7 +75,7 @@ let commands () =
          cctxt#message "%s\n" source >>= fun () ->
          return ()) ;
 
-    command ~group ~desc: "ask the node to run a program"
+    command ~group ~desc: "Ask the node to run a program."
       (args3 trace_stack_switch amount_arg no_print_source_flag)
       (prefixes [ "run" ; "program" ]
        @@ Program.source_param
@@ -96,7 +96,7 @@ let commands () =
             run ~amount ~program ~storage ~input cctxt#block cctxt >>= fun res ->
             print_run_result cctxt ~show_source ~parsed:program res)) ;
 
-    command ~group ~desc: "ask the node to typecheck a program"
+    command ~group ~desc: "Ask the node to typecheck a program."
       (args3 show_types_switch emacs_mode_switch no_print_source_flag)
       (prefixes [ "typecheck" ; "program" ]
        @@ Program.source_param
@@ -112,7 +112,7 @@ let commands () =
            res
            cctxt) ;
 
-    command ~group ~desc: "ask the node to typecheck a data expression"
+    command ~group ~desc: "Ask the node to typecheck a data expression."
       (args1 no_print_source_flag)
       (prefixes [ "typecheck" ; "data" ]
        @@ Cli_entries.param ~name:"data" ~desc:"the data to typecheck"
@@ -135,14 +135,15 @@ let commands () =
              cctxt#error "ill-typed data") ;
 
     command ~group
-      ~desc: "ask the node to compute the hash of a data expression \
-              using the same algorithm as script instruction H"
+      ~desc: "Ask the node to hash a data expression.\n\
+              The returned hash is the same as what Michelson \
+              instruction `H` would have produced."
       no_options
       (prefixes [ "hash" ; "data" ]
        @@ Cli_entries.param ~name:"data" ~desc:"the data to hash"
          data_parameter
        @@ prefixes [ "of" ; "type" ]
-       @@ Cli_entries.param ~name:"type" ~desc:"the type of the data"
+       @@ Cli_entries.param ~name:"type" ~desc:"type of the data"
          data_parameter
        @@ stop)
       (fun () data typ cctxt ->
@@ -156,16 +157,17 @@ let commands () =
              cctxt#error "ill-formed data") ;
 
     command ~group
-      ~desc: "ask the node to compute the hash of a data expression \
-              using the same algorithm as script instruction H, sign it using \
-              a given secret key, and display it using the format expected by \
-              script instruction CHECK_SIGNATURE"
+      ~desc: "Ask the node to hash a data expression.\n\
+              Uses the same algorithm as Michelson instruction `H` to \
+              produce the hash, signs it using a given secret key, and \
+              displays it using the format expected by Michelson \
+              instruction `CHECK_SIGNATURE`."
       no_options
       (prefixes [ "hash" ; "and" ; "sign" ; "data" ]
        @@ Cli_entries.param ~name:"data" ~desc:"the data to hash"
          data_parameter
        @@ prefixes [ "of" ; "type" ]
-       @@ Cli_entries.param ~name:"type" ~desc:"the type of the data"
+       @@ Cli_entries.param ~name:"type" ~desc:"type of the data"
          data_parameter
        @@ prefixes [ "for" ]
        @@ Client_keys.Secret_key.alias_param