diff --git a/docs/reference/issuers.rst b/docs/reference/issuers.rst
index e66512b63..88e7af994 100644
--- a/docs/reference/issuers.rst
+++ b/docs/reference/issuers.rst
@@ -11,7 +11,7 @@ An example of an Issuer type is ACME. A simple ACME issuer could be defined as:
 
 .. code-block:: yaml
    :linenos:
-   :emphasize-lines: 11, 16
+   :emphasize-lines: 11, 20
 
    apiVersion: cert-manager.io/v1alpha2
    kind: Issuer
@@ -27,8 +27,12 @@ An example of an Issuer type is ACME. A simple ACME issuer could be defined as:
        # Name of a secret used to store the ACME account private key
        privateKeySecretRef:
          name: letsencrypt-prod
-       # Enable HTTP01 validations
-       http01: {}
+       solvers:
+       # An empty 'selector' means that this solver matches all domains
+       - selector: {}
+         http01:
+           ingress:
+             class: nginx
 
 
 This is the simplest of ACME issuers - it specifies no DNS-01 challenge
@@ -70,7 +74,7 @@ those credentials to perform the ACME DNS01 challenge with route53.
 
 .. code-block:: yaml
    :linenos:
-   :emphasize-lines: 14-15
+   :emphasize-lines: 17-18
 
    apiVersion: cert-manager.io/v1alpha2
    kind: ClusterIssuer
@@ -82,11 +86,14 @@ those credentials to perform the ACME DNS01 challenge with route53.
        email: user@example.com
        privateKeySecretRef:
          name: letsencrypt-prod
-       dns01:
-         providers:
-         - name: route53
-           route53:
-             region: us-east-1
+       solvers:
+       # An empty 'selector' means that this solver matches all domains
+       - selector: {}
+         dns01:
+           providers:
+           - name: route53
+             route53:
+               region: us-east-1
 
 It is important to note that the ``route53`` section does not specify any
 ``accessKeyID`` or ``secretAccessKeySecretRef``. If either of these are
diff --git a/docs/tasks/upgrading/upgrading-0.10-0.11.rst b/docs/tasks/upgrading/upgrading-0.10-0.11.rst
index 2520cbf20..c1ec7550f 100644
--- a/docs/tasks/upgrading/upgrading-0.10-0.11.rst
+++ b/docs/tasks/upgrading/upgrading-0.10-0.11.rst
@@ -106,3 +106,10 @@ your cluster for you.
 
 You should make sure to update _all_ Ingress resources to ensure that your
 certificates continue to be kept up to date.
+
+Issuer/ClusterIssuer solvers
+============================
+
+Support for the deprecated ``spec.http01`` or ``spec.dns01`` fields in ``Issuer`` and ``ClusterIssuer`` have been removed. Any ``Issuer`` or ``ClusterIssuer`` objects must be converted to use the equivalent ``spec.solvers[].http01`` or ``spec.solvers[].dns01`` syntax. You can read more about the Issuer resource in the  :doc:`Issuer reference docs </reference/issuers>`.
+
+Any issuers that haven't been converted will result the ``cert-manager`` pod being unable to find any solvers at the expected location. This will result in errors like the following: ``no configured challenge solvers can be used for this challenge``
diff --git a/docs/tutorials/acme/http-validation.rst b/docs/tutorials/acme/http-validation.rst
index 8263eb5a5..314c271ab 100644
--- a/docs/tutorials/acme/http-validation.rst
+++ b/docs/tutorials/acme/http-validation.rst
@@ -56,9 +56,9 @@ change this email address to a valid one that you own. It is commonly used to
 send expiry notices when your certificates are coming up for renewal. The
 generated private key is stored in a Secret named ``letsencrypt-staging``.
 
-The presence of the ``http01`` field simply enables the HTTP-01 challenge for this
-Issuer.
-No further configuration is necessary or currently possible.
+We must provide one or more Solvers for handling the ACME challenge. In this case
+we want to use HTTP validation so we specify an ``http01`` Solver. We could
+optionally map different domains to use different Solver configurations.
 
 Once we have created the above Issuer we can use it to obtain a certificate.