Documentation review

src/doc/docs/faq.md

@@ -75,6 +75,16 @@ You can still revoke certificates without account key pair though, see [here](us
 
 **Solution:** It is a difficult situation that is caused by an ambiguous specification, but it is like it is now. Since _acme4j_ follows the intention of the RFC author, I take the position that the _acme4j_ implementation is correct. Please open a bug report at the CA, and refer to [this issue](https://github.com/shred/acme4j/issues/123). If the two tokens are split at a position so the first token won't have trailing base64 padding bits, the CA service can be implemented in a way that is compatible to both interpretations.
 
+## Suddenly acme4j starts throwing `AcmeUserActionRequiredException` everywhere! How can I fix that?
+
+**Sympton:** Many _acme4j_ methods suddenly throw a `AcmeUserActionRequiredException` after interacting with the server. It is impossible to order certificates.
+
+**Cause:** The CA has probably changed its terms of service and wants you to accept them before resuming.
+
+**Solution:** Invoke `AcmeUserActionRequiredException.getInstance()` to get an URL of a web page that describes all further steps to be taken. You might also be able to resolve the issue by logging into your CA's account, but that is up to the CA's discretion.
+
+Unfortunately, manual action is required in any case, there is no way to automate this process. This is an intentional protocol decision, and _acme4j_ is just the messenger.
+
 ## Where can I find more help?
 
 * [Let's Encrypt Documentation](https://letsencrypt.org/docs/)

src/doc/docs/usage/order.md

@@ -177,7 +177,7 @@ To get a list of all current orders of your account, invoke `Account.getOrders()
 Note that for reasons lying in the ACME protocol, the result is an `Iterator<Order>` and not a list. Also, any invocation of `Iterator.next()` can initiate a network call to the CA, and may throw an `AcmeProtocolException` if there was an error.
 
 !!! important
-    This method is a mandatory part of RFC-8555. Still, as of now, this functionality has not been implemented in all [Boulder](https://github.com/letsencrypt/boulder) based CAs (like Let's Encrypt) and will throw an `AcmeNotSupportedException`. Also see [this issue](https://github.com/letsencrypt/boulder/issues/3335). At the moment, the only workaround is to store `Order` location URLs (or other resource URLs) locally along with the certificates.
+    This method is a mandatory part of RFC-8555. Still, as of now, this functionality has not been implemented in all [Boulder](https://github.com/letsencrypt/boulder) based CAs (like Let's Encrypt) and will throw an `AcmeNotSupportedException`. Also see [this issue](https://github.com/letsencrypt/boulder/issues/3335). At the moment, the only workaround is to store `Order` location URLs (or other resource URLs) locally along with the certificates, see the [Resources and Persistence](./persistence.md) chapter.
 
 
 ## Wildcard Certificates

src/doc/docs/usage/persistence.md

@@ -9,7 +9,7 @@ All CA related resources are derived from the `AcmeResource` class:
 * `Order`: A certificate order
 * `RenewalInfo`: Renewal information
 
-These classes reflect the state of the corresponding resource on the ACME server side. Except of `Certificate`, they also keep a copy of the current resource state that can be updated via `update()`.
+These classes reflect the state of the corresponding resource on the ACME server side. They also keep a copy of the current resource state that can be updated via `update()`. The only exception is the `Certificate` resource, which will never change its state and thus does not need to be updated.
 
 ## Resource Location