[docs] develop: improve cleos how to

docs/02_cleos/02_how-to-guides/how-to-stake-resource.md

@@ -1,28 +1,110 @@
-## Goal
+## Overview
 
-Stake resource for your account
+This how-to guide provides instructions on how to stake resources, NET and/or CPU, for your account using the `cleos` CLI tool.
 
 ## Before you begin
 
-* Install the currently supported version of `cleos`
+* Install the currently supported version of `cleos`.
 
-* Ensure the reference system contracts from `eosio.contracts` repository is deployed and used to manage system resources
+* Ensure the [reference system contracts](https://developers.eos.io/manuals/eosio.contracts/v1.9/build-and-deploy) are deployed and used to manage system resources.
 
 * Understand the following:
-  * What is an account
-  * What is network bandwidth
-  * What is CPU bandwidth
+  * What is an [account](https://developers.eos.io/welcome/latest/glossary/index/#account).
+  * What is [NET bandwidth](https://developers.eos.io/manuals/eosio.contracts/latest/key-concepts/net).
+  * What is [CPU bandwidth](https://developers.eos.io/manuals/eosio.contracts/latest/key-concepts/cpu).
 
-## Steps
+## Command Reference
 
-Stake 0.01 SYS network bandwidth for `alice`
+See the following reference guides for command line usage and related options for the `cleos` command:
+
+* The [`delegatebw` cleos sub-command](https://developers.eos.io/manuals/eos/latest/cleos/command-reference/system/system-delegatebw).
+
+## Procedure
+
+The following steps show:
+
+1. [How to stake NET bandwidth.](#1-stake-net-bandwidth)
+2. [How to stake CPU bandwidth.](#2-stake-cpu-bandwidth)
+3. [How to stake NET and CPU bandwidth.](#3-stake-net-and-cpu-bandwidth)
+
+### 1. Stake NET bandwidth
+
+Run the following command to stake `0.01 SYS` of NET bandwidth for `alice` account from `bob` account:
 
 ```sh
-cleos system delegatebw alice alice "0 SYS" "0.01 SYS"
+cleos system delegatebw alice bob "0.01 SYS" "0 SYS"
+```
+
+Where:
+
+* `alice` = the account for which the NET bandwidth is staked.
+* `bob` = the account that pays the `0.01 SYS` for the NET bandwidth staked.
+* "0.01 SYS" = the amount of system tokens `SYS` allocated to stake NET bandwidth.
+* "0 SYS" = the amount of system tokens `SYS` allocated to stake CPU bandwidth.
+
+Example output:
+
+```console
+executed transaction: 5487afafd67bf459a20fcc2dbc5d0c2f0d1f10e33123eaaa07088046fd18e3ae  192 bytes  503 us
+#         eosio <= eosio::delegatebw            {"from":"bob","receiver":"alice","stake_net_quantity":"0.01 SYS","stake_cpu_quanti...
+#   eosio.token <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 EOS","memo":"stake bandwidth"}
+#  alice <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}
+#   eosio.stake <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}
 ```
 
-Stake 0.01 SYS CPU bandwidth for `alice`:
+### 2. Stake CPU bandwidth
+
+Run the following command to stake `0.01 SYS` of CPU bandwidth for `alice` account from `bob` account:
 
 ```sh
-cleos system delegatebw alice alice "0.01 SYS" "0 SYS"
-```
+cleos system delegatebw alice bob "0 SYS" "0.01 SYS"
+```
+
+Where:
+
+* `alice` = the account for which the CPU bandwidth is staked.
+* `bob` = the account that pays the `0.01 SYS` for the CPU bandwidth staked.
+* "0 SYS" = the amount of system tokens `SYS` allocated to stake NET bandwidth.
+* "0.01 SYS" = the amount of system tokens `SYS` allocated to stake CPU bandwidth.
+
+Example output:
+
+```console
+executed transaction: 5487afafd67bf459a20fcc2dbc5d0c2f0d1f10e33123eaaa07088046fd18e3ae  192 bytes  503 us
+#         eosio <= eosio::delegatebw            {"from":"bob","receiver":"alice","stake_net_quantity":"0.0000 SYS","stake_cpu_quanti...
+#   eosio.token <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 EOS","memo":"stake bandwidth"}
+#  alice <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}
+#   eosio.stake <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}
+```
+
+### 3. Stake NET and CPU bandwidth
+
+Run the following command to stake `0.01 SYS` of NET and `0.02 SYS` of CPU bandwidth for `alice` account from `bob` account:
+
+```sh
+cleos system delegatebw alice bob "0.01 SYS" "0.02 SYS"
+```
+
+Where:
+
+* `alice` = the account for which the NET and CPU bandwidth is staked.
+* `bob` = the account that pays `0.01 SYS` for the NET and `0.02 SYS` for the CPU bandwidth staked.
+* "0.01 SYS" = the amount of system tokens `SYS` allocated to stake NET bandwidth.
+* "0.02 SYS" = the amount of system tokens `SYS` allocated to stake CPU bandwidth.
+
+Example output:
+
+```console
+executed transaction: 5487afafd67bf459a20fcc2dbc5d0c2f0d1f10e33123eaaa07088046fd18e3ae  192 bytes  503 us
+#         eosio <= eosio::delegatebw            {"from":"bob","receiver":"alice","stake_net_quantity":"0.01 SYS","stake_cpu_quanti...
+#   eosio.token <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 EOS","memo":"stake bandwidth"}
+#  alice <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}
+#   eosio.stake <= eosio.token::transfer        {"from":"bob","to":"eosio.stake","quantity":"0.01 SYS","memo":"stake bandwidth"}
+```
+
+[[info|An account can stake to itself]]
+| An account can stake resources to itself, that is, `bob` account can be substituted in the above examples with `alice`, provided `alice` account holds sufficient `SYS` tokens. That means `alice` account stakes resources to itself.
+
+## Summary
+
+In conclusion, the above instructions show how to stake CPU and/or NET bandwidth from one account to another or to itself.

docs/02_cleos/02_how-to-guides/how-to-submit-a-transaction.md

@@ -1,18 +1,35 @@
-## Goal
+## Overview
 
-Push a transaction
+This how-to guide provides instructions on how to submit, or push, a transaction using the `cleos` CLI tool.
 
 ## Before you begin
 
 * Install the currently supported version of `cleos`
 
 * Understand the following:
-  * What is a transaction
-  * How to generate a valid transaction JSON
+  * What is a [transaction](https://developers.eos.io/welcome/latest/glossary/index/#transaction).
+  * How to generate a valid transaction JSON.
+    * Consult [cleos push transaction reference](https://developers.eos.io/manuals/eos/latest/cleos/command-reference/push/push-transaction), and pay attention to option `-d` and `-j`.
+    * Consult [push transaction operation](https://developers.eos.io/manuals/eos/latest/nodeos/plugins/chain_api_plugin/api-reference/index#operation/push_transactions) for chain api plug-in, and pay attention to the payload definition.
 
-## Steps
+## Command Reference
 
-* Create a JSON snippet contains a valid transaction such as the following:
+See the following reference guides for command line usage and related options for the `cleos` command:
+
+* The [`push transaction` cleos sub-command](https://developers.eos.io/manuals/eos/latest/cleos/command-reference/push/push-transaction).
+
+## Procedure
+
+The following steps show how to:
+
+1. [Create the transaction as JSON snippet.](#1-create-the-transaction-as-json-snippet)
+2. [Send the transaction.](#2-send-the-transaction)
+
+### 1. Create the transaction as JSON snippet
+
+You can create the JSON snippet defining the transaction in two ways:
+
+* Create a JSON snippet which contains a valid transaction and uses hex format for `data` field.
 
 ```JSON
 {
@@ -39,12 +56,12 @@ Push a transaction
 }
 ```
 
-* You can also create a JSON snippet that uses clear text JSON for `data` field.
+* Alternatively, you can also create a JSON snippet that uses clear text JSON for `data` field.
 
 [[info]]
-| Be aware that if a clear text `data` field is used, cleos need to fetch copies of required ABIs using `nodeos` API. That operation has a performance overhead on `nodeos`
+| Be aware that if a clear text `data` field is used, `cleos` needs to fetch the smart contract's ABI using `nodeos` API. This operation has an overall performance overhead for both `cleos` and `nodeos`. On the other hand if hex data is used in the `data` field then the ABI fetching is not executed and thus the total time to send and execute the transaction is faster.
 
-```JSON
+```json
 {
   "expiration": "2019-08-01T07:15:49",
   "ref_block_num": 34881,
@@ -74,18 +91,22 @@ Push a transaction
 }
 ```
 
-* Execute the following command:
+### 2. Send the transaction
+
+You can send the transaction you created as JSON snippet in two ways:
+
+* You can send the transaction stored in `TRX_FILE.json` file:
 
 ```sh
 cleos push transaction TRX_FILE.json
 ```
 
-* Submit a transaction from a JSON:
+* Alternatively, you can send the transaction using the JSON content directly:
 
 ```sh
-cleos push transaction JSON
+cleos push transaction '{"expiration": "2019-08-01T07:15:49", "ref_block_num": 34881,"ref_block_prefix": 2972818865,"max_net_usage_words": 0,"max_cpu_usage_ms": 0,"delay_sec": 0,"context_free_actions": [],"actions": [{"account": "eosio.token","name": "transfer","authorization": [{"actor": "han","permission": "active"}],"data": {"from": "han","to": "eosio","quantity": "0.0001 SYS","memo": "m"}}],"transaction_extensions": [],"context_free_data": []}'
 ```
 
-<!---
-Link to Push Action API
--->
+## Summary
+
+In conclusion, the above instructions show how to submit, or push, a transaction using the `cleos` CLI tool.

docs/02_cleos/02_how-to-guides/how-to-transfer-an-eosio.token-token.md

@@ -1,21 +1,47 @@
-## Goal
+## Overview
 
-Transfer token created by eosio.token contract
+This how-to guide provides instructions on how to transfer tokens created by `eosio.token` contract.
 
 ## Before you begin
 
-* Install the currently supported version of `cleos`
+* Install the currently supported version of `cleos`.
 
-* You are going to transfer a token created by eosio.token contract and eosio.token contract has been deployed on the network which you are connected to
+* `eosio.token` contract is deployed on the network you are connected to.
 
 * Understand the following:
-  * What is a transaction
-  * Token transfers are irrevertable 
+  * What is a [transaction](https://developers.eos.io/welcome/latest/glossary/index/#transaction).
+  * Token transfers are irreversible.
 
-## Steps
+## Command Reference
 
-Assume you would like to transfer `0.0001 SYS` token to an account called `bob` from an account called `alice`, execute the following:
+See the following reference guides for command line usage and related options for the `cleos` command:
+
+* The [`transfer` cleos sub-command](https://developers.eos.io/manuals/eos/latest/cleos/command-reference/transfer).
+
+## Procedure
+
+The following steps show how to transfer `0.0001 SYS` tokens to an account called `bob` from an account called `alice`:
 
 ```sh
 cleos transfer alice bob "0.0001 SYS" "Hodl!" -p alice@active
 ```
+
+Where:
+
+* `alice` = the account that transfers the tokens.
+* `bob` = the account that receives the tokens.
+* "0.0001 SYS" = the amount and the token symbol sent.
+* "Hodl!" = the message, or memo, that is accompanying the transaction.
+
+Example output:
+
+```console
+executed transaction: 800835f28659d405748f4ac0ec9e327335eae579a0d8e8ef6330e78c9ee1b67c  128 bytes  1073 us
+#   eosio.token <= eosio.token::transfer        {"from":"alice","to":"bob","quantity":"25.0000 SYS","memo":"m"}
+#         alice <= eosio.token::transfer        {"from":"alice","to":"bob","quantity":"25.0000 SYS","memo":"m"}
+#           bob <= eosio.token::transfer        {"from":"alice","to":"bob","quantity":"25.0000 SYS","memo":"m"}
+```
+
+## Summary
+
+In conclusion, the above instructions show how to transfer tokens created by `eosio.token` contract from one account to another.

docs/02_cleos/02_how-to-guides/how-to-vote.md

@@ -1,30 +1,47 @@
-## Goal
+## Overview
 
-Vote for a block producer
+This how-to guide provides instructions on how to vote for block producers.
 
 ## Before you begin
 
-* Install the currently supported version of `cleos`
+* Install the latest version of `cleos`.
 
-* Ensure the reference system contracts from `eosio.contracts` repository is deployed and used to manage system resources
+* Ensure the [reference system contracts](https://developers.eos.io/manuals/eosio.contracts/latest/build-and-deploy) are deployed and used to manage system resources.
 
 * Understand the following:
-  * What is a block producer
-  * How does voting works
+  * What is a [block producer](https://developers.eos.io/welcome/latest/protocol/consensus_protocol#11-block-producers).
+  * How does [voting](https://developers.eos.io/manuals/eosio.contracts/latest/key-concepts/vote) work.
 
-* Unlock your wallet
+* Unlock your wallet.
 
-## Steps
+## Command Reference
 
-Assume you are going to vote for blockproducer1 and blockproducer2 from an account called `eosiotestts2`, execute the following:
+See the following reference guides for command line usage and related options for the `cleos` command:
+
+* The [`system voteproducer prods` cleos sub-command](https://developers.eos.io/manuals/eos/latest/cleos/command-reference/system/system-voteproducer-prods).
+
+## Procedure
+
+The following steps show:
+
+1. How to vote for blockproducer1 and blockproducer2 from an account called `eosiotestts2`:
 
 ```sh
 cleos system voteproducer prods eosiotestts2 blockproducer1 blockproducer2
 ```
 
-This should produce similar output as below:
+Where:
+
+* eosiotestts2 = the account that votes.
+* blockproducer1 and blockproducer2 = the accounts receiving the votes. The number of accounts receiving the votes can vary from one to multiple. Maximum default number of block producers one account can vote for is 30.
+
+Example output:
 
 ```console
 executed transaction: 2d8b58f7387aef52a1746d7a22d304bbbe0304481d7751fc4a50b619df62676d  128 bytes  374 us
 #         eosio <= eosio::voteproducer          {"voter":"eosiotestts2","proxy":"","producers":["blockproducer1","blockproducer2"]}
 ```
+
+## Summary
+
+In conclusion, the above instructions show how to vote for block producers.