diff --git a/substrate/README.adoc b/substrate/README.adoc
index aaab6df3cc2f2cafcb730b1001e85bd4375a5e42..6afa1cf4e1305658a975a01afb96a951051c6bd3 100644
--- a/substrate/README.adoc
+++ b/substrate/README.adoc
@@ -160,7 +160,7 @@ It won't do much until you start producing blocks though, so to do that you'll n
 
 [source, shell]
 ----
-substrate --chain ~/mychain.json --validator --key ...
+substrate --chain ~/mychain.json --validator
 ----
 
 You can distribute `mychain.json` so that everyone can synchronize and (depending on your authorities list) validate on your chain.
@@ -378,6 +378,38 @@ git checkout -b v1.0 origin/v1.0
 
 You can then follow the same steps for building and running as described above in <<flaming-fir>>.
 
+== Key management
+
+Keys in Substrate are stored in the keystore in the file system. To store keys into this keystore,
+you need to use one of the two provided RPC calls. If your keys are encrypted or should be encrypted
+by the keystore, you need to provide the key using one of the cli arguments `--password`,
+`--password-interactive` or `--password-filename`.
+
+=== Recommended RPC call
+
+For most users who want to run a validator node, the `author_rotateKeys` RPC call is sufficient.
+The RPC call will generate `N` Session keys for you and return their public keys. `N` is the number
+of session keys configured in the runtime. The output of the RPC call can be used as input for the
+`session::set_keys` transaction.
+
+```
+curl -H 'Content-Type: application/json' --data '{ "jsonrpc":"2.0", "method":"author_rotateKeys", "id":1 }' localhost:9933
+```
+
+=== Advanced RPC call
+
+If the Session keys need to match a fixed seed, they can be set individually key by key. The RPC call
+expects the key seed and the key type. The key types supported by default in Substrate are listed
+https://github.com/paritytech/substrate/blob/master/core/primitives/src/crypto.rs#L767[here], but the
+user can declare any key type.
+
+```
+curl -H 'Content-Type: application/json' --data '{ "jsonrpc":"2.0", "method":"author_insertKey", "params":["KEY_TYPE", "SEED"],"id":1 }' localhost:9933
+```
+
+`KEY_TYPE` - needs to be replaced with the 4-character key type identifier.
+`SEEED` - is the seed of the key.
+
 == Documentation
 
 === Viewing documentation for Substrate packages
diff --git a/substrate/core/cli/src/params.rs b/substrate/core/cli/src/params.rs
index 72adc552b9ecd86d6f5dfcff1f37989e2075bff7..0f58527287eb7dcaa169582605ab7160279fd5af 100644
--- a/substrate/core/cli/src/params.rs
+++ b/substrate/core/cli/src/params.rs
@@ -441,7 +441,11 @@ lazy_static::lazy_static! {
 	/// The Cli values for all test accounts.
 	static ref TEST_ACCOUNTS_CLI_VALUES: Vec<KeyringTestAccountCliValues> = {
 		keyring::Sr25519Keyring::iter().map(|a| {
-			let help = format!("Shortcut for `--key //{} --name {}`.", a, a);
+			let help = format!(
+				"Shortcut for `--name {} --validator` with session keys for `{}` added to keystore.",
+				a,
+				a,
+			);
 			let conflicts_with = keyring::Sr25519Keyring::iter()
 				.filter(|b| a != *b)
 				.map(|b| b.to_string().to_lowercase())