From 84d6fdfc37f732a85bdb1c00e0ee1aab9a601baa Mon Sep 17 00:00:00 2001
From: Chris Chinchilla <chris@chrischinchilla.com>
Date: Tue, 7 Jul 2020 14:41:23 +0200
Subject: [PATCH 1/3] Start review of getting started guide

---
 docs.wrm/getting-started.wrm | 57 ++++++++++++++++++++++++------------
 docs.wrm/index.wrm           |  2 +-
 2 files changed, 39 insertions(+), 20 deletions(-)

diff --git a/docs.wrm/getting-started.wrm b/docs.wrm/getting-started.wrm
index 49fc13329..0428e3124 100644
--- a/docs.wrm/getting-started.wrm
+++ b/docs.wrm/getting-started.wrm
@@ -3,14 +3,14 @@ _section: Getting Started @<getting-started>
 
 _subsection: Installing @<installing>
 
-The various Classes and Functions are available to be imported
+Ethers' various Classes and Functions are available to import
 manually from sub-packages under the [@ethersproject](link-ethers-npm)
 organization but for most projects, the umbrella package is the
 easiest way to get started.
 
 _code: @lang<shell>
 
-/home/ricmoo> npm install --save ethers@next
+/home/ricmoo> npm install --save ethers
 
 
 _subsection: Importing @<importing>
@@ -32,7 +32,7 @@ It is generally better practice (for security reasons) to copy the
 [ethers library](link-ethers-js) to your own webserver and serve it
 yourself.
 
-For quick demos or prototyping though, it can be loaded in your
+For quick demos or prototyping though, you can load it in your
 Web Applications from our CDN.
 
 
@@ -64,8 +64,8 @@ $Signer:    A Signer is a class which (usually) in some way directly or
             and transactions to authorize the network to charge your account
             ether to perform operations.
 $Contract:  A Contract is an abstraction which represents a connection to a
-            specific contract on the Ethereum Network, so that it can be
-            used like a normal JavaScipt object.
+            specific contract on the Ethereum Network, so that applications 
+            can use it like a normal JavaScipt object.
 
 
 | **Provider**     | $Provider      |
@@ -90,14 +90,34 @@ const provider = new ethers.providers.Web3Provider(window.ethereum)
 
 // The Metamask plugin also allows signing transactions to
 // send ether and pay to change state within the blockchain.
-// For this, we need the account signer...
+// For this, you need the account signer...
 const signer = provider.getSigner()
 
+_subsection: Connecting to Ethereum: RPC @<getting-started--connecting-rpc>
+
+The [JSON-RPC API](link-jsonrpc) is another popular method for interacting
+with Ethereum and is available in all major Ethereum node implementations
+(e.g. [[link-geth]] and [[link-parity]]) as well as many
+third-party web services (e.g. [[link-infura]]). It typically provides:
+
+- A connection to the Ethereum network (a [[Provider]])
+- Holds your private key and can sign thing (a [[Signer]])
+
+_code: Connecting to an RPC client @lang<script>
+
+// If you don't specify a //url//, Ethers connects to the default 
+// (i.e. ``http:/\/localhost:8545``)
+const provider = new ethers.providers.JsonRpcProvider();
+
+// The provider also allows signing transactions to
+// send ether and pay to change state within the blockchain.
+// For this, we need the account signer...
+const signer = provider.getSigner()
 
 _heading: Querying the Blockchain @<getting-started--querying>
 
 Once you have a [[Provider]], you have a read-only connection to the
-blockchain, which can be used to query the current state, fetch historic
+blockchain, which you can use to query the current state, fetch historic
 logs, look up deployed code and so on.
 
 _code: Basic Queries @lang<javascript>
@@ -106,16 +126,16 @@ _code: Basic Queries @lang<javascript>
 provider.getBlockNumber()
 //!
 
-// Get the balance of an account (by address or ENS name)
+// Get the balance of an account (by address or ENS name, if supported by network)
 balance = await provider.getBalance("ethers.eth")
 //! async balance
 
-// Often you will need to format the output for the user
-// which prefer to see values in ether (instead of wei)
+// Often you need to format the output to something more user-friendly,
+// such as in ether (instead of wei)
 ethers.utils.formatEther(balance)
 //!
 
-// Or if a user enters a string in an input field, you may need
+// If a user enters a string in an input field, you may need
 // to convert it from ether (as a string) to wei (as a BigNumber)
 ethers.utils.parseEther("1.0")
 //!
@@ -138,10 +158,10 @@ A Contract is an abstraction of program code which lives on the
 Ethereum blockchain.
 
 The [[Contract]] object makes it easier to use an on-chain
-Contract as a normal JavaScript object, with the method all
+Contract as a normal JavaScript object, with the methods
 mapped to encoding and decoding data for you.
 
-If you are familiar with Databases, this is similar to ORM.
+If you are familiar with Databases, this is similar to an ORM.
 
 In order to communicate with the Contract on-chain, this class
 needs to know what methods are available and how to encode and
@@ -149,26 +169,25 @@ decode the data, which is what the //Application Binary Interface// (API)
 provides.
 
 This class is a meta-class, which means its methods are constructed
-at runtime, when you pass in the ABI to the constructor it uses that
+at runtime, when you pass in the ABI to the constructor it uses it
 to determine which methods to add.
 
 While a on-chain Contract may have many methods available, you can safely ignore
 any methods you don't need or use, providing a smaller subset of the ABI to
 the contract.
 
-An ABI often comes from the Solidity or Vyper compiler, but may also be
-placed in the code easily using the Human-Readable ABI, which the following
-examples use.
+An ABI often comes from the Solidity or Vyper compiler, but you can use the
+Human-Readable ABI in code, which the following examples use.
 
 _code: Connecting to the DAI Contract @lang<javascript>
 
-// We can use an ENS name for the contract address
+// You can also use an ENS name for the contract address
 const daiAddress = "dai.tokens.ethers.eth";
 
 // The ERC-20 Contract ABI, which is a common contract interface
 // for tokens (this is the Human-Readable ABI format)
 const daiAbi = [
-  // Some simple details about the token
+  // Some details about the token
   "function name() view returns (string)",
   "function symbol() view returns (string)",
 
diff --git a/docs.wrm/index.wrm b/docs.wrm/index.wrm
index 3e178823a..b01889551 100644
--- a/docs.wrm/index.wrm
+++ b/docs.wrm/index.wrm
@@ -5,7 +5,7 @@ _subsection: What is Ethers? @<preamble>
 The ethers.js library aims to be a complete and compact library for
 interacting with the Ethereum Blockchain and its ecosystem. It was
 originally designed for use with [ethers.io](link-ethersio) and
-has since expanded into a much more general-purpose library.
+has since expanded into a more general-purpose library.
 
 _subsection: Features @<features>
 

From fb46e0fd79e9eb31e82a404f48ab0b56a52fab91 Mon Sep 17 00:00:00 2001
From: Chris Chinchilla <chris.ward@ethereum.org>
Date: Tue, 14 Jul 2020 13:13:52 +0200
Subject: [PATCH 2/3] Further review

---
 docs.wrm/api/providers/index.wrm            | 2 +-
 docs.wrm/api/providers/jsonrpc-provider.wrm | 2 +-
 docs/v5/README.md                           | 1 +
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs.wrm/api/providers/index.wrm b/docs.wrm/api/providers/index.wrm
index c6166ecd7..d10d71a58 100644
--- a/docs.wrm/api/providers/index.wrm
+++ b/docs.wrm/api/providers/index.wrm
@@ -9,7 +9,7 @@ cover the vast majority of use-cases, but also includes the
 necessary functions and classes for sub-classing if a more
 custom configuration is necessary.
 
-Most users should be able to simply use the [[providers-getDefaultProvider]].
+Most users should use the [[providers-getDefaultProvider]].
 
 
 _subsection: Default Provider @<providers-getDefaultProvider>
diff --git a/docs.wrm/api/providers/jsonrpc-provider.wrm b/docs.wrm/api/providers/jsonrpc-provider.wrm
index 65df445b4..eedc06186 100644
--- a/docs.wrm/api/providers/jsonrpc-provider.wrm
+++ b/docs.wrm/api/providers/jsonrpc-provider.wrm
@@ -1,6 +1,6 @@
 _section: JsonRpcProvider  @<JsonRpcProvider> @INHERIT<[[Provider]]> @SRC<providers:class.JsonRpcProvider>
 
-The [JSON-RPC API](link-jsonrpc) is a very popular method for interacting
+The [JSON-RPC API](link-jsonrpc) is a popular method for interacting
 with Ethereum and is available in all major Ethereum node implementations
 (e.g. [[link-geth]] and [[link-parity]]) as well as many
 third-party web services (e.g. [[link-infura]])
diff --git a/docs/v5/README.md b/docs/v5/README.md
index fb67364de..d2382ba25 100644
--- a/docs/v5/README.md
+++ b/docs/v5/README.md
@@ -21,6 +21,7 @@ Developer Documentation
   * [Importing](getting-started)
   * [Common Terminology](getting-started)
   * [Connecting to Ethereum: Metamask](getting-started)
+  * [Connecting to Ethereum: RPC](getting-started)
   * [Contracts](getting-started)
   * [Signing Messages](getting-started)
 * [Ethereum Basics](concepts)

From 3ac0aeaac62a284154cf46dc24f540ee4ee7aa75 Mon Sep 17 00:00:00 2001
From: Chris Chinchilla <chris.ward@ethereum.org>
Date: Tue, 14 Jul 2020 14:05:55 +0200
Subject: [PATCH 3/3] Further review

---
 docs.wrm/getting-started.wrm | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs.wrm/getting-started.wrm b/docs.wrm/getting-started.wrm
index 0428e3124..8642d53b0 100644
--- a/docs.wrm/getting-started.wrm
+++ b/docs.wrm/getting-started.wrm
@@ -161,18 +161,18 @@ The [[Contract]] object makes it easier to use an on-chain
 Contract as a normal JavaScript object, with the methods
 mapped to encoding and decoding data for you.
 
-If you are familiar with Databases, this is similar to an ORM.
+If you are familiar with Databases, this is similar to an ////Object Relational Mapper// (ORM).
 
 In order to communicate with the Contract on-chain, this class
 needs to know what methods are available and how to encode and
 decode the data, which is what the //Application Binary Interface// (API)
 provides.
 
-This class is a meta-class, which means its methods are constructed
-at runtime, when you pass in the ABI to the constructor it uses it
+This class is a //meta-class//, which means its methods are constructed
+at runtime, and when you pass in the ABI to the constructor it uses it
 to determine which methods to add.
 
-While a on-chain Contract may have many methods available, you can safely ignore
+While an on-chain Contract may have many methods available, you can safely ignore
 any methods you don't need or use, providing a smaller subset of the ABI to
 the contract.
 
@@ -243,8 +243,8 @@ _heading: State Changing Methods @<getting-started--writing>
 _code: Sending DAI @lang<script>
 
 // The DAI Contract is currently connected to the Provider,
-// which is read-only. We need to connect to a Signer, so
-// that we can pay to send state-changing transactions.
+// which is read-only. You need to connect to a Signer, so
+// that you can pay to send state-changing transactions.
 const daiWithSigner = contract.connect(signer);
 
 // Each DAI has 18 decimal places
@@ -334,7 +334,7 @@ daiContract.queryFilter(filterFrom, 9843470, 9843480)
 // number of entries; but they provide some useful examples
 //
 
-// List all transfers I sent in the last 10,000 blocks
+// List all transfers sent in the last 10,000 blocks
 daiContract.queryFilter(filterFrom, -10000)
 
 // List all transfers ever sent to me
@@ -350,8 +350,8 @@ const signer = ethers.Wallet.createRandom();
 //!
 // </hide>
 
-// To sign a simple string, which can often be used for
-// logging into a service, such as CryptoKitties simply
+// To sign a simple string, which are used for
+// logging into a service, such as CryptoKitties,
 // pass the string in.
 signature = await signer.signMessage("Hello World");
 //! async signature
@@ -362,7 +362,7 @@ signature = await signer.signMessage("Hello World");
 // data it MUST be an Array (or TypedArray)
 //
 
-// This string is 66 chacacters long
+// This string is 66 characters long
 message = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
 
 // This array representation is 32 bytes long