Doc

README.md

@@ -28,26 +28,29 @@ One tricky thing about the ACME API is that it is paranoid about replay
 attacks. Every request that you make to the API needs to have a unique nonce.
 Every response from the API has a new nonce, passed in a header.
 
-The pattern is to create a session, call the `newNonce` API to get an initial
-nonce, then call one or more APIs to do the work. Functions in this library
-keep track of the nonce in the session. So you make a an API call with a
-session parameter, then use the returned session to make the next call.
+First create a session, then call the `newNonce` API to get an initial
+nonce. Use that nonce when calling the API. Take the nonce from that API response
+and use it to call another API function, and so on.
+
+Functions in this library keep track of the nonce in the session. So you make a
+an API call with a session parameter, then use the returned session to make the
+next call.
 
 ### Accounts
 
-To make API calls, you need to first generate a cryptographic account key,
-`account_key` for the client. You then create an account on the server,
-identified by an account key id, `account_kid`, a URL on the server.
+Before making API calls, you first need to generate a cryptographic account key
+(`account_key`). You then create an account on the server, identified by an
+account key id, `account_kid`, a URL on the server.
 
 Generate an account key:
 
 ```elixir
 {:ok, account_key} = AcmeClient.generate_account_key()
 ```
 
-The `account_key` is a struct. After generating it, you would normally put it
-into the application environment. The following functions convert the struct to
-and from a binary string.
+The `account_key` is a struct. After generating it, you would normally save
+it as a secret for your app. The following functions convert the struct to and
+from a binary string.
 
 ```elixir
 # Convert key struct into string
@@ -85,7 +88,7 @@ and gets the initial nonce.
 If you call it with no parameters, it reads them from the application environment.
 
 ```elixir
-{:ok, session} = AcmeClient.create_session(account_key: account_key, account_kid: account_kid)
+{:ok, session} = AcmeClient.create_session()
 ```
 
 ### Orders
@@ -103,35 +106,21 @@ type/value map.
 
 On success, it returns a map where `url` is the URL of the created order and
 `object` has its attributes. Make sure to keep track of the URL, or it may be
-impossible to complete the order. The Let's Encrypt API does not support the
-ability to get the outstanding orders for an acount, as specified in RFC8555.
+impossible to complete the order, as the Let's Encrypt API does not support the
+RFC8555 API functions to get the outstanding orders for an acount.
 
 ### Authorizations
 
-The order response has an "authorization" URL for each domain name.
-We call these URLs to create challenge responses.
+The order response has an authorization URL for each domain name in the cert.
+The authorization manages challenge responses which are used to prove that you
+control the domain.
+
+Create challenge responses from the order:
 
 ```elixir
 {:ok, session, authorizations} = AcmeClient.create_challenge_responses(session, order.object)
 ```
 
-A challenge response is a way to prove ownership of the domain.
-This library supports two mechanisms, DNS and HTTP.
-
-For DNS, you create a DNS TXT record with the response to the challenge, and the ACME service
-will do a lookup to verify that the response it is expecting is there.
-
-```
-_acme-challenge.www.example.com. 300 IN TXT <response>
-```
-
-For HTTP, the ACME service will make an HTTP request to your web server at a "well known" URL,
-and verify that the response is there.
-
-```
-http://example.com/.well-known/acme-challenge/<response>
-```
-
 The `authorizations` response looks like this:
 
 ```
@@ -183,6 +172,22 @@ The `authorizations` response looks like this:
 ]}
 ```
 
+This library supports two challenge response mechanisms, DNS and HTTP.
+
+For DNS, you create a DNS TXT record with the response to the challenge, and
+the ACME service does a lookup to verify that the response it is expecting is there.
+
+```
+_acme-challenge.www.example.com. 300 IN TXT <response>
+```
+
+For HTTP, the ACME service makes an HTTP request to your web server at a "well known" URL,
+verifying that the response is there.
+
+```
+http://example.com/.well-known/acme-challenge/<response>
+```
+
 For DNS validation, get the `dns-01` responses in DNS format:
 
 ```elixir